This is DGAlgebras.info, produced by Macaulay2, version 1.26.06

DGAlgebras -- Data types and basic functions on differential graded (DG) Algebras.
**********************************************************************************

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

This package is used to define and manipulate DG algebras.

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

Some documentation was added by Daniel Rostamloo and David Eisenbud.

Authors
=======

  * Frank Moore (see http://www.math.wfu.edu/Faculty/Moore.html )
    <moorewf@wfu.edu>
  * Keller VandeBogert (see https://sites.google.com/view/kellervandebogert/
    home ) <keller.v@uky.edu>

Version
=======

This documentation describes version 2.1 of DGAlgebras, released June 4, 2026.

Citation
========

If you have used this package in your research, please cite it as follows:

+----------------------------------------------------------------------------+
|@misc{DGAlgebrasSource,                                                     |
|  title = {{DGAlgebras: Data type for DG algebras. Version~2.1}},           |
|  author = {Frank Moore and Keller VandeBogert},                            |
|  howpublished = {A \emph{Macaulay2} package available at                   |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}}|
|}                                                                           |
|                                                                            |
+----------------------------------------------------------------------------+

Exports
=======

  * Types
      * DGAlgebra -- The class of all DGAlgebras
      * DGAlgebraMap -- The class of DG algebra maps
      * DGIdeal -- The class of d-closed graded ideals of a DG
        algebra
      * DGModule -- The class of DG modules over a DG algebra
      * DGModuleMap -- The class of morphisms of DG modules
        over a common DG algebra
      * DGQuotientModule -- The class of quotient DG
        modules M / S
      * DGSubmodule -- The class of d-closed submodules of
        a DG module
  * Functions and commands
      * acyclicClosure -- Tate's construction of a
        semifree acyclic DG algebra extension
      * adjoinGenerators -- Adjoin new free generators
        to a DG module with prescribed differentials
      * adjoinVariables -- Extend a DG algebra by a
        user-chosen list of cycles to be killed
      * "inclusion" -- see ambient, -- Accessors for the ambient
        object, inclusion, projection, and killed submodule
      * "projection" -- see ambient, -- Accessors for the
        ambient object, inclusion, projection, and killed submodule
      * "subDGModule" -- see ambient, -- Accessors for the
        ambient object, inclusion, projection, and killed submodule
      * baseChange -- Transport a DG algebra along a ring
        map on its base
      * blockDiff -- prepares a map for display
      * deviations -- Computes the deviations of the input
        ring, complex, or power series.
      * deviationsToPoincare -- Computes the power
        series corresponding to a set of deviations.
      * "tensorFactors" -- see DGAlgebra ** DGAlgebra,
        -- Exterior tensor product of DG algebras over a common
        ground ring
      * "tensorInclusions" -- see DGAlgebra ** DGAlgebra,
        -- Exterior tensor product of DG algebras over a
        common ground ring
      * dgAlgebraMap -- Define a DG algebra map between DG
        algebras.
      * dgAlgebraMultMap -- Returns the chain map
        corresponding to multiplication by a cycle.
      * dgComplex -- Package a DG algebra or DG module as a
        Complex of free base-ring modules
      * dgIdeal -- Construct a DG ideal from a list, matrix, or
        ideal of generators
      * dgModuleMap -- Construct a DGModuleMap from a
        matrix or from a list of image Vectors
      * dgModuleSummary -- Tabulate hom-degree-wise
        generator counts and free-rank counts for a DG module
      * dgQuotientModule -- Construct the quotient DG
        module M / S
      * dgSubmodule -- Construct a d-closed submodule of a
        DG module
      * differential -- The list of generator
        differentials stored in a DG algebra or DG module
      * displayBlockDiff -- Shows natural
        decomposition of a map in the Tate resolution
      * displayModuleBlockDiff -- Pretty-print
        the labeled block matrix of a DG module differential
      * ensureDGAlgebraCaches -- Guarantee that
        the standard cache sub-tables are present
      * expandGeomSeries -- Expand a geometric series
        to a specified degree.
      * "findNaryTrivialMasseyOperation" -- see
        findTrivialMasseyOperation, -- Finds a
        trivial Massey operation on a set of generators of H(A)
      * findTrivialMasseyOperation -- Finds
        a trivial Massey operation on a set of generators of H(A)
      * freeDGAlgebra -- Construct a free DG algebra with
        given generator degrees
      * freeDGModule -- Construct a free DG module over a
        DG algebra
      * generatorDegrees -- The hom-degrees (and
        optional internal degrees) of the DG generators
      * generatorTable -- Display the generator list of
        a DG module with hom-degrees and differentials
      * getBasis -- Get a basis for a particular homological
        degree of a DG algebra.
      * getBoundaryPreimage -- Attempt to find a
        preimage of a boundary under the differential of a DGAlgebra.
      * getDegNModule -- Extract the degree-n strand of a
        graded algebra as a module over its degree-zero piece
      * getGenerators -- Cycles whose classes generate
        the homology algebra of a DG algebra
      * homologyAlgebra -- Compute the homology algebra
        of a DGAlgebra.
      * homologyClass -- Computes the element of the
        homology algebra corresponding to a cycle in a DGAlgebra.
      * homologyModule -- Compute the homology of a
        DGModule as a module over a DGAlgebra.
      * identityDGAlgebraMap -- The identity
        DGAlgebraMap on a DG algebra
      * identityDGModuleMap -- The identity
        DGModuleMap on a DG module
      * invalidateDGAlgebraCache -- Discard
        cached derived data so that it is recomputed from scratch
      * isAcyclic -- Determine whether a DG algebra has no
        higher homology
      * isDGIdeal -- Test whether an ideal of A.natural is
        closed under the differential of A
      * isDGSubmodule -- Test whether the image of an
        inclusion matrix is d-closed
      * isFreeDGModule -- Is the underlying
        A.natural-module free?
      * isGolod -- Determines if a ring is Golod
      * isGolodHomomorphism -- Determines if the
        canonical map from the ambient ring is Golod
      * isHomologyAlgebraTrivial -- Determines
        if the homology algebra of a DGAlgebra is trivial
      * isMinimalSemifreeResolution -- Test
        whether a semifree DG module is minimal over its DG algebra
      * isValidDGAlgebra -- Structural invariant check
        for a DG algebra
      * isValidDGModule -- Structural-invariant check
        on a DG module
      * isWellDefinedDifferential -- Semantic
        check that d^2 = 0 for a DG algebra or DG module
      * "isZero" -- see isZero(DGModule), -- Does
        the DG object have no natural generators?
      * killCycles -- Adjoin variables to kill non-bounding
        cycles in the lowest positive degree
      * killHomologyAtDegree -- Adjoin variables
        killing the homology of a DG algebra at a prescribed degree
      * koszulComplexDGA -- The Koszul complex on the
        variables of a ring, as a DG algebra
      * koszulComplexDGM -- The Koszul complex of a
        module as a DG module
      * liftToDGMap -- Lift a ring homomorphism in degree
        zero to a DG algebra morphism
      * liftToDGModuleMap -- Lift an image of
        hom-degree-0 generators to a full DGModuleMap
      * masseyTripleProduct -- Computes the Massey
        triple product of a set of cycles or homology classes
      * maxDegree -- Computes the maximum homological degree
        of a DGAlgebra
      * minimalModel -- Build the minimal DG algebra
        resolution of a quotient ring
      * minimalSemifreeResolution -- Build a
        minimal semifree DG module resolution over a DG algebra
      * minimizeDGModule (missing documentation)
      * moduleBlockDiff -- The hom-degree-n
        differential of a DG module as a labeled block matrix
      * moduleDifferential -- The hom-degree-n
        differential of a DG module as a matrix over the base ring
      * polyDifferential -- Matrix and element-level
        differentials of a DG algebra
      * polyDiffMonomial -- Leibniz rule on a single
        monomial of a DG algebra
      * restrictDifferential -- Synonym for
        subDGAlgebra, named to match the restricted-differential vocabulary
      * semifreeResolution -- Build a semifree DG
        module resolving a module over the base ring
      * setDiff -- Install or replace the differential on a DG
        algebra
      * subDGAlgebra -- The sub-DG algebra generated by a
        chosen subset of DG generators
      * toComplex -- Converts a DGAlgebra to a Complex
      * toComplexMap -- Construct the ComplexMap
        associated to a DGAlgebraMap
      * torAlgebra -- Computes the Tor algebra of a ring
      * torMap -- Compute the map of Tor algebras associated to
        a RingMap.
      * truncateGenerators -- Restrict a DG algebra
        to its generators of hom-degree strictly above a bound
      * underlyingAlgebra -- The graded-commutative
        algebra carrying the DG structure
      * underlyingRing -- The commutative base ring of a
        DG algebra or DG module
      * zeroDGModuleMap -- The zero DGModuleMap between
        two DG modules over a common algebra
      * zerothHomology -- The zeroth homology of a DG
        algebra as a ring
  * Methods
      * - DGModuleMap (missing documentation)
      * "acyclicClosure(DGAlgebra)" -- see acyclicClosure,
        -- Tate's construction of a semifree acyclic DG algebra
        extension
      * acyclicClosure(Ring) -- Tate's acyclic
        closure of the residue field, starting from the Koszul complex
      * "adjoinGenerators(DGModule,List)" -- see adjoinGenerators,
        -- Adjoin new free generators to a DG module with
        prescribed differentials
      * "adjoinVariables(DGAlgebra,List)" -- see adjoinVariables,
        -- Extend a DG algebra by a user-chosen list of cycles
        to be killed
      * "ambient(DGIdeal)" -- see ambient, -- Accessors for the
        ambient object, inclusion, projection, and killed submodule
      * "ambient(DGQuotientModule)" -- see ambient, -- Accessors
        for the ambient object, inclusion, projection, and killed submodule
      * "ambient(DGSubmodule)" -- see ambient, -- Accessors for
        the ambient object, inclusion, projection, and killed submodule
      * "inclusion(DGSubmodule)" -- see ambient, -- Accessors
        for the ambient object, inclusion, projection, and killed submodule
      * "projection(DGQuotientModule)" -- see ambient, --
        Accessors for the ambient object, inclusion, projection, and killed
        submodule
      * "subDGModule(DGQuotientModule)" -- see ambient, --
        Accessors for the ambient object, inclusion, projection, and killed
        submodule
      * annihilator(DGQuotientModule),
        -- The DG ideal of A annihilating a DG quotient module
      * annihilator(DGSubmodule) -- The DG
        ideal of A annihilating a DG submodule
      * "baseChange(DGAlgebra,Ring)" -- see baseChange, --
        Transport a DG algebra along a ring map on its base
      * "baseChange(DGAlgebra,RingMap)" -- see baseChange, --
        Transport a DG algebra along a ring map on its base
      * "blockDiff(DGAlgebra,ZZ)" -- see blockDiff, --
        prepares a map for display
      * cokernel(DGModuleMap) -- Cokernel of
        a DG module map as a DG quotient module of its target
      * components(DGModule) (missing documentation)
      * degree(DGModuleMap) (missing documentation)
      * degrees(DGModule) -- Multi-degrees of the
        natural generators of a DG module
      * "degrees(DGQuotientModule)" -- see degrees(DGModule),
        -- Multi-degrees of the natural generators of a
        DG module
      * "degrees(DGSubmodule)" -- see degrees(DGModule),
        -- Multi-degrees of the natural generators of a
        DG module
      * "deviations(Complex)" -- see deviations, -- Computes
        the deviations of the input ring, complex, or power series.
      * "deviations(Ring)" -- see deviations, -- Computes the
        deviations of the input ring, complex, or power series.
      * "deviations(RingElement,List)" -- see deviations, --
        Computes the deviations of the input ring, complex, or power series.
      * "deviationsToPoincare(HashTable)" -- see deviationsToPoincare,
        -- Computes the power series corresponding to a
        set of deviations.
      * DGAlgebra ** DGAlgebra -- Exterior
        tensor product of DG algebras over a common ground ring
      * "tensorFactors(DGAlgebra)" -- see DGAlgebra ** DGAlgebra,
        -- Exterior tensor product of DG algebras
        over a common ground ring
      * "tensorInclusions(DGAlgebra)" -- see DGAlgebra ** DGAlgebra,
        -- Exterior tensor product of DG algebras
        over a common ground ring
      * DGAlgebra ** Ring -- Base change of a DG
        algebra to another ring
      * DGAlgebra / DGIdeal -- Quotient DG algebra
        by a DG ideal
      * "dgAlgebraMap(DGAlgebra,DGAlgebra,Matrix)" -- see dgAlgebraMap,
        -- Define a DG algebra map between DG algebras.
      * "isWellDefined(DGAlgebraMap)" -- see dgAlgebraMap,
        -- Define a DG algebra map between DG algebras.
      * DGAlgebraMap * DGAlgebraMap, --
        Composition of DG algebra maps
      * DGAlgebraMap ** DGAlgebraMap,
        -- Tensor product of DG algebra maps
      * DGAlgebraMap ** Ring -- Base change of
        a DG algebra map along a ring map
      * DGAlgebraMap == DGAlgebraMap (missing documentation)
      * "dgAlgebraMultMap(DGAlgebra,RingElement)" -- see
        dgAlgebraMultMap, -- Returns the chain map
        corresponding to multiplication by a cycle.
      * "dgComplex(DGAlgebra)" -- see dgComplex, -- Package a
        DG algebra or DG module as a Complex of free base-ring modules
      * "dgComplex(DGModule)" -- see dgComplex, -- Package a
        DG algebra or DG module as a Complex of free base-ring modules
      * "dgIdeal(DGAlgebra,Ideal)" -- see dgIdeal, -- Construct
        a DG ideal from a list, matrix, or ideal of generators
      * "dgIdeal(DGAlgebra,List)" -- see dgIdeal, -- Construct a
        DG ideal from a list, matrix, or ideal of generators
      * "dgIdeal(DGAlgebra,Matrix)" -- see dgIdeal, -- Construct
        a DG ideal from a list, matrix, or ideal of generators
      * DGIdeal * DGIdeal -- Product of two DG
        ideals
      * DGIdeal * DGModule (missing documentation)
      * DGIdeal * DGSubmodule (missing documentation)
      * DGIdeal ** Ring -- Base change of a DG
        ideal along a ring map
      * DGIdeal + DGIdeal -- Sum of two DG ideals
      * DGIdeal _colon_ DGIdeal -- Ideal quotient
        (colon) of two DG ideals
      * DGIdeal == DGIdeal -- Equality and
        containment of DG ideals
      * "isSubset(DGIdeal,DGIdeal)" -- see DGIdeal == DGIdeal,
        -- Equality and containment of DG ideals
      * DGIdeal ^ ZZ -- Nonnegative integer power of a DG
        ideal
      * DGModule ** DGModule -- Exterior
        tensor product of DG modules over DG algebras sharing a ground ring
      * DGModule ** Module -- Exterior tensor
        product of a DG module with an ordinary free module
      * "Module ** DGModule" -- see DGModule ** Module,
        -- Exterior tensor product of a DG module with an ordinary free
        module
      * DGModule ** Ring -- Base change of a DG
        module along a ring map
      * DGModule ++ DGModule (missing documentation)
      * DGModule / DGSubmodule -- Quotient DG
        module: M / S
      * "dgModuleMap(DGModule,DGModule,List)" -- see dgModuleMap,
        -- Construct a DGModuleMap from a matrix or from a list of
        image Vectors
      * "dgModuleMap(DGModule,DGModule,Matrix)" -- see dgModuleMap,
        -- Construct a DGModuleMap from a matrix or from a list of
        image Vectors
      * DGModuleMap * DGModuleMap (missing documentation)
      * DGModuleMap * Number (missing documentation)
      * DGModuleMap * QQ (missing documentation)
      * DGModuleMap * RingElement (missing documentation)
      * DGModuleMap * ZZ (missing documentation)
      * DGModuleMap ** DGModuleMap, --
        Tensor product of DG module maps
      * DGModuleMap ** Ring -- Base change of a
        DG module map along a ring map
      * DGModuleMap + DGModuleMap (missing documentation)
      * DGModuleMap - DGModuleMap (missing documentation)
      * DGModuleMap == DGModuleMap, --
        Elementary predicates and constructors for DGModuleMaps
      * "isHomogeneous(DGModuleMap)" -- see DGModuleMap == DGModuleMap,
        -- Elementary predicates and constructors
        for DGModuleMaps
      * "isQuasiIsomorphism(DGModuleMap)" -- see DGModuleMap == DGModuleMap,
        -- Elementary predicates and
        constructors for DGModuleMaps
      * "map(DGModule,DGModule,ZZ)" -- see DGModuleMap == DGModuleMap,
        -- Elementary predicates and constructors
        for DGModuleMaps
      * DGModuleMap == ZZ (missing documentation)
      * DGModuleMap Vector (missing documentation)
      * "dgModuleSummary(DGModule)" -- see dgModuleSummary,
        -- Tabulate hom-degree-wise generator counts and
        free-rank counts for a DG module
      * "dgModuleSummary(DGModule,ZZ)" -- see dgModuleSummary,
        -- Tabulate hom-degree-wise generator counts and
        free-rank counts for a DG module
      * "dgQuotientModule(DGModule,DGSubmodule)" -- see dgQuotientModule,
        -- Construct the quotient DG module M / S
      * DGQuotientModule ** Module, --
        Exterior tensor product of a DG quotient module with an ordinary free
        module
      * "Module ** DGQuotientModule" -- see DGQuotientModule ** Module,
        -- Exterior tensor product of a DG
        quotient module with an ordinary free module
      * DGQuotientModule ** Ring -- Base
        change of a DG quotient module along a ring map
      * "dgSubmodule(DGModule,List)" -- see dgSubmodule, --
        Construct a d-closed submodule of a DG module
      * "dgSubmodule(DGModule,Matrix)" -- see dgSubmodule,
        -- Construct a d-closed submodule of a DG module
      * DGSubmodule ** Module -- Exterior
        tensor product of a DG submodule with an ordinary free module
      * "Module ** DGSubmodule" -- see DGSubmodule ** Module,
        -- Exterior tensor product of a DG submodule with an
        ordinary free module
      * DGSubmodule ** Ring -- Base change of a
        DG submodule along a ring map
      * DGSubmodule + DGSubmodule -- Sum of
        two DG submodules of a common ambient
      * DGSubmodule == DGSubmodule, --
        Equality and containment of DG submodules
      * "isSubset(DGSubmodule,DGSubmodule)" -- see DGSubmodule == DGSubmodule,
        -- Equality and containment of
        DG submodules
      * diff(DGAlgebra,RingElement),
        -- Apply the differential of a DGAlgebra to a ring element
      * diff(DGModule,Vector) -- Apply the
        DG module differential to an element
      * diff(DGQuotientModule,Vector)
        -- Apply the induced differential
        on a DG quotient module to an element
      * "differential(DGAlgebra)" -- see differential, --
        The list of generator differentials stored in a DG algebra or DG module
      * "differential(DGModule)" -- see differential, --
        The list of generator differentials stored in a DG algebra or DG module
      * directSum(DGModule) (missing documentation)
      * "displayBlockDiff(DGAlgebra,Array,Array)" -- see
        displayBlockDiff, -- Shows natural decomposition of a
        map in the Tate resolution
      * "displayBlockDiff(DGAlgebra,List,List)" -- see displayBlockDiff,
        -- Shows natural decomposition of a map in the Tate
        resolution
      * "displayBlockDiff(DGAlgebra,VisibleList)" -- see
        displayBlockDiff, -- Shows natural decomposition of a
        map in the Tate resolution
      * "displayBlockDiff(DGAlgebra,ZZ)" -- see displayBlockDiff,
        -- Shows natural decomposition of a map in the Tate
        resolution
      * "displayModuleBlockDiff(DGModule,List,List)" -- see
        displayModuleBlockDiff, -- Pretty-print the
        labeled block matrix of a DG module differential
      * "displayModuleBlockDiff(DGModule,ZZ)" -- see
        displayModuleBlockDiff, -- Pretty-print the
        labeled block matrix of a DG module differential
      * "ensureDGAlgebraCaches(DGAlgebra)" -- see ensureDGAlgebraCaches,
        -- Guarantee that the standard cache sub-tables
        are present
      * "ensureDGAlgebraCaches(DGModule)" -- see ensureDGAlgebraCaches,
        -- Guarantee that the standard cache sub-tables
        are present
      * "expandGeomSeries(List,ZZ)" -- see expandGeomSeries,
        -- Expand a geometric series to a specified degree.
      * "expandGeomSeries(RingElement,ZZ)" -- see expandGeomSeries,
        -- Expand a geometric series to a specified degree.
      * "findNaryTrivialMasseyOperation(DGAlgebra,List,HashTable,ZZ)" -- see
        findTrivialMasseyOperation, -- Finds
        a trivial Massey operation on a set of generators of H(A)
      * "findTrivialMasseyOperation(DGAlgebra)" -- see
        findTrivialMasseyOperation, -- Finds a
        trivial Massey operation on a set of generators of H(A)
      * "freeDGAlgebra(Ring,List)" -- see freeDGAlgebra,
        -- Construct a free DG algebra with given generator degrees
      * "freeDGModule(DGAlgebra,List)" -- see freeDGModule,
        -- Construct a free DG module over a DG algebra
      * "generatorDegrees(DGAlgebra)" -- see generatorDegrees,
        -- The hom-degrees (and optional internal degrees) of
        the DG generators
      * "generatorDegrees(DGModule)" -- see generatorDegrees,
        -- The hom-degrees (and optional internal degrees) of
        the DG generators
      * generators(DGAlgebra) (missing documentation)
      * "generatorTable(DGModule)" -- see generatorTable,
        -- Display the generator list of a DG module with hom-degrees and
        differentials
      * "getBasis(ZZ,DGAlgebra)" -- see getBasis, -- Get a
        basis for a particular homological degree of a DG algebra.
      * getBasis(ZZ,DGModule) -- Basis of
        the hom-degree-n piece of a DG module
      * getBasis(ZZ,Ring) -- Get a basis for a
        degree of a ring.
      * "getBoundaryPreimage(DGAlgebra,List)" -- see getBoundaryPreimage,
        -- Attempt to find a preimage of a boundary under
        the differential of a DGAlgebra.
      * "getBoundaryPreimage(DGAlgebra,RingElement)" -- see
        getBoundaryPreimage, -- Attempt to find a preimage
        of a boundary under the differential of a DGAlgebra.
      * getBoundaryPreimage(DGModule,List)
        -- Lift a list of boundaries
        sharing a hom-degree through the module differential
      * getBoundaryPreimage(DGModule,Vector)
        -- Lift a boundary in a DG
        module to a preimage under the differential
      * "getDegNModule(ZZ,Ring,Ring)" -- see getDegNModule,
        -- Extract the degree-n strand of a graded algebra as a
        module over its degree-zero piece
      * "getGenerators(DGAlgebra)" -- see getGenerators,
        -- Cycles whose classes generate the homology algebra of a DG algebra
      * HH DGAlgebra -- The homology algebra of a DG
        algebra
      * HH DGAlgebraMap -- The induced ring map on
        homology algebras
      * HH DGModule -- The graded homology of a DG module
        as a module over HH(A)
      * "homologyModule(DGModule)" -- see HH DGModule, --
        The graded homology of a DG module as a module over HH(A)
      * HH DGModuleMap -- The induced map on graded
        homology modules over HH(A)
      * HH DGQuotientModule -- The graded homology
        of a DG quotient module
      * "homologyModule(DGQuotientModule)" -- see HH DGQuotientModule,
        -- The graded homology of a DG quotient module
      * HH_ZZ DGAlgebra -- Computes the homology of a
        DG algebra as a module
      * HH_ZZ DGModule -- The degree-n homology of a
        DG module as a module over the base ring
      * HH_ZZ DGQuotientModule -- The degree-n
        homology of a DG quotient module
      * homology(DGModuleMap,ZZ) -- The
        induced map on degree-n homology of a DG module map
      * "homologyAlgebra(DGAlgebra)" -- see homologyAlgebra,
        -- Compute the homology algebra of a DGAlgebra.
      * "homologyClass(DGAlgebra,RingElement)" -- see homologyClass,
        -- Computes the element of the homology algebra
        corresponding to a cycle in a DGAlgebra.
      * homologyClass(DGModule,Vector)
        -- The homology class of a cycle
        in a DG module
      * "homologyModule(DGAlgebra,Module)" -- see homologyModule,
        -- Compute the homology of a DGModule as a module over
        a DGAlgebra.
      * ideal(DGIdeal) (missing documentation)
      * "identityDGAlgebraMap(DGAlgebra)" -- see identityDGAlgebraMap,
        -- The identity DGAlgebraMap on a DG algebra
      * "identityDGModuleMap(DGModule)" -- see identityDGModuleMap,
        -- The identity DGModuleMap on a DG module
      * image(DGModuleMap) -- Image of a DG
        module map as a DG submodule of its target
      * intersect(DGIdeal,DGIdeal), --
        Intersection of two DG ideals
      * intersect(DGSubmodule,DGSubmodule)
        -- Intersection of two DG
        submodules of a common ambient
      * "invalidateDGAlgebraCache(DGAlgebra)" -- see
        invalidateDGAlgebraCache, -- Discard cached
        derived data so that it is recomputed from scratch
      * "invalidateDGAlgebraCache(DGModule)" -- see
        invalidateDGAlgebraCache, -- Discard cached
        derived data so that it is recomputed from scratch
      * "isAcyclic(DGAlgebra)" -- see isAcyclic, -- Determine
        whether a DG algebra has no higher homology
      * isAcyclic(DGModule) -- Determine
        whether a DG module has vanishing positive-degree homology
      * isAcyclic(DGQuotientModule), --
        Determine whether a DG quotient module has vanishing positive-degree
        homology
      * "isDGIdeal(DGAlgebra,Ideal)" -- see isDGIdeal, -- Test
        whether an ideal of A.natural is closed under the differential of A
      * "isDGSubmodule(DGModule,Matrix)" -- see isDGSubmodule,
        -- Test whether the image of an inclusion matrix is
        d-closed
      * "isFreeDGModule(DGModule)" -- see isFreeDGModule,
        -- Is the underlying A.natural-module free?
      * "isFreeDGModule(DGSubmodule)" -- see isFreeDGModule,
        -- Is the underlying A.natural-module free?
      * "isGolod(Ring)" -- see isGolod, -- Determines if a ring
        is Golod
      * "isGolodHomomorphism(QuotientRing)" -- see isGolodHomomorphism,
        -- Determines if the canonical map from the
        ambient ring is Golod
      * isHomogeneous(DGAlgebra), --
        Determine if the DGAlgebra respects the gradings of the ring it is
        defined over.
      * isHomogeneous(DGIdeal) -- Predicates
        on a DG ideal
      * "isZero(DGIdeal)" -- see isHomogeneous(DGIdeal),
        -- Predicates on a DG ideal
      * isHomogeneous(DGModule) -- Test
        whether the underlying graded module is homogeneous
      * "isHomogeneous(DGQuotientModule)" -- see isHomogeneous(DGModule),
        -- Test whether the underlying graded
        module is homogeneous
      * "isHomogeneous(DGSubmodule)" -- see isHomogeneous(DGModule),
        -- Test whether the underlying graded
        module is homogeneous
      * "isHomologyAlgebraTrivial(DGAlgebra)" -- see
        isHomologyAlgebraTrivial, -- Determines if
        the homology algebra of a DGAlgebra is trivial
      * isInjective(DGModuleMap) (missing documentation)
      * isIsomorphism(DGModuleMap) (missing documentation)
      * "isMinimalSemifreeResolution(DGModule)" -- see
        isMinimalSemifreeResolution, -- Test
        whether a semifree DG module is minimal over its DG algebra
      * isQuasiIsomorphism(DGAlgebraMap)
        -- Determine whether a DG algebra
        map induces an isomorphism on homology
      * isSurjective(DGModuleMap) (missing documentation)
      * "isValidDGAlgebra(DGAlgebra)" -- see isValidDGAlgebra,
        -- Structural invariant check for a DG algebra
      * "isValidDGModule(DGModule)" -- see isValidDGModule,
        -- Structural-invariant check on a DG module
      * isWellDefined(DGAlgebra) -- Check
        that a DG algebra has correct structure and a differential that squares
        to zero
      * isWellDefined(DGIdeal) -- Verify
        that a DGIdeal has correct structure and is d-closed
      * isWellDefined(DGModule) -- Check
        that a DG module has correct structure and that its differential
        squares to zero
      * isWellDefined(DGModuleMap), --
        Check that a DG module map has correct structure and is a chain map
      * isWellDefined(DGQuotientModule)
        -- Check that a DG quotient module
        has a well-defined differential
      * isWellDefined(DGSubmodule), --
        Check that a DG submodule is d-closed in its ambient DG module
      * "isWellDefinedDifferential(DGAlgebra)" -- see
        isWellDefinedDifferential, -- Semantic check
        that d^2 = 0 for a DG algebra or DG module
      * "isWellDefinedDifferential(DGModule)" -- see
        isWellDefinedDifferential, -- Semantic check
        that d^2 = 0 for a DG algebra or DG module
      * isZero(DGModule) -- Does the DG object
        have no natural generators?
      * "isZero(DGQuotientModule)" -- see isZero(DGModule),
        -- Does the DG object have no natural generators?
      * "isZero(DGSubmodule)" -- see isZero(DGModule),
        -- Does the DG object have no natural generators?
      * kernel(DGModuleMap) -- Kernel of a DG
        module map as a DG submodule of its source
      * "killCycles(DGAlgebra)" -- see killCycles, -- Adjoin
        variables to kill non-bounding cycles in the lowest positive degree
      * killCycles(DGModule) -- Adjoin free
        generators to kill the lowest nonvanishing homology of a DG module
      * "killHomologyAtDegree(DGAlgebra,ZZ)" -- see killHomologyAtDegree,
        -- Adjoin variables killing the homology of a DG
        algebra at a prescribed degree
      * "koszulComplexDGA(Ring)" -- see koszulComplexDGA,
        -- The Koszul complex on the variables of a ring, as
        a DG algebra
      * koszulComplexDGA(Ideal) -- The
        Koszul complex on the generators of an ideal, as a DG algebra
      * koszulComplexDGA(List) -- The Koszul
        complex on a list of ring elements, as a DG algebra
      * "koszulComplexDGM(DGAlgebra,Module)" -- see koszulComplexDGM,
        -- The Koszul complex of a module as a DG module
      * "koszulComplexDGM(Module)" -- see koszulComplexDGM,
        -- The Koszul complex of a module as a DG module
      * "liftToDGMap(DGAlgebra,DGAlgebra,RingMap)" -- see liftToDGMap,
        -- Lift a ring homomorphism in degree zero to a DG algebra
        morphism
      * "liftToDGModuleMap(DGModule,DGModule,List)" -- see
        liftToDGModuleMap, -- Lift an image of hom-degree-0
        generators to a full DGModuleMap
      * "liftToDGModuleMap(DGModule,DGModule,Matrix)" -- see
        liftToDGModuleMap, -- Lift an image of hom-degree-0
        generators to a full DGModuleMap
      * "liftToDGModuleMap(DGModule,DGModule,Vector)" -- see
        liftToDGModuleMap, -- Lift an image of hom-degree-0
        generators to a full DGModuleMap
      * "masseyTripleProduct(DGAlgebra,RingElement,RingElement,RingElement)" --
        see masseyTripleProduct, -- Computes the
        Massey triple product of a set of cycles or homology classes
      * masseyTripleProduct(DGAlgebra,ZZ,ZZ,ZZ)
        -- Computes the
        matrix representing all triple Massey operations.
      * "maxDegree(DGAlgebra)" -- see maxDegree, -- Computes
        the maximum homological degree of a DGAlgebra
      * maxDegree(DGModule) -- Largest
        hom-degree present in a DG module
      * maxDegree(DGQuotientModule), --
        Largest hom-degree present in a DG quotient module
      * "generators(DGIdeal)" -- see mingens(DGIdeal),
        -- Basic accessors on a DG ideal
      * mingens(DGIdeal) -- Basic accessors on a
        DG ideal
      * "module(DGIdeal)" -- see mingens(DGIdeal),
        -- Basic accessors on a DG ideal
      * "numgens(DGIdeal)" -- see mingens(DGIdeal),
        -- Basic accessors on a DG ideal
      * "ring(DGIdeal)" -- see mingens(DGIdeal), --
        Basic accessors on a DG ideal
      * "minimalModel(Ideal)" -- see minimalModel, -- Build
        the minimal DG algebra resolution of a quotient ring
      * "minimalModel(QuotientRing)" -- see minimalModel,
        -- Build the minimal DG algebra resolution of a quotient ring
      * "minimalSemifreeResolution(DGAlgebra,Module)" -- see
        minimalSemifreeResolution, -- Build a
        minimal semifree DG module resolution over a DG algebra
      * "minimalSemifreeResolution(Module)" -- see
        minimalSemifreeResolution, -- Build a
        minimal semifree DG module resolution over a DG algebra
      * minimizeDGModule(DGModule) (missing documentation)
      * module(DGSubmodule) (missing documentation)
      * "moduleBlockDiff(DGModule,ZZ)" -- see moduleBlockDiff,
        -- The hom-degree-n differential of a DG module as a
        labeled block matrix
      * "moduleDifferential(ZZ,DGModule)" -- see moduleDifferential,
        -- The hom-degree-n differential of a DG module as
        a matrix over the base ring
      * net(DGAlgebra) -- Short-form display of a DG
        algebra
      * net(DGAlgebraMap) -- Short-form display
        of a DG algebra map
      * net(DGIdeal) (missing documentation)
      * net(DGModule) (missing documentation)
      * net(DGModuleMap) (missing documentation)
      * net(DGQuotientModule) (missing documentation)
      * net(DGSubmodule) (missing documentation)
      * Number * DGModuleMap (missing documentation)
      * numgens(DGAlgebra) (missing documentation)
      * numgens(DGModule) -- Number of natural
        generators of a DG module (or sub- or quotient module)
      * "numgens(DGQuotientModule)" -- see numgens(DGModule),
        -- Number of natural generators of a DG module
        (or sub- or quotient module)
      * "numgens(DGSubmodule)" -- see numgens(DGModule),
        -- Number of natural generators of a DG module
        (or sub- or quotient module)
      * "polyDifferential(DGAlgebra,RingElement)" -- see
        polyDifferential, -- Matrix and element-level
        differentials of a DG algebra
      * "polyDifferential(ZZ,DGAlgebra)" -- see polyDifferential,
        -- Matrix and element-level differentials of a DG
        algebra
      * "polyDiffMonomial(DGAlgebra,RingElement)" -- see
        polyDiffMonomial, -- Leibniz rule on a single
        monomial of a DG algebra
      * "minimalPresentation(DGAlgebra)" -- see prune(DGAlgebra),
        -- Pruning a DG algebra is the identity
      * prune(DGAlgebra) -- Pruning a DG algebra
        is the identity
      * "minimalPresentation(DGAlgebraMap)" -- see prune(DGAlgebraMap),
        -- Pruning a DG algebra map is the identity
      * prune(DGAlgebraMap) -- Pruning a DG
        algebra map is the identity
      * "minimalPresentation(DGIdeal)" -- see prune(DGIdeal),
        -- Trim a DG ideal down to a minimal generating set
      * prune(DGIdeal) -- Trim a DG ideal down to a
        minimal generating set
      * "minimalPresentation(DGModule)" -- see prune(DGModule),
        -- Pruning a DG module is the identity
      * prune(DGModule) -- Pruning a DG module is
        the identity
      * "minimalPresentation(DGModuleMap)" -- see prune(DGModuleMap),
        -- Pruning a DG module map is the identity
      * prune(DGModuleMap) -- Pruning a DG
        module map is the identity
      * "minimalPresentation(DGQuotientModule)" -- see
        prune(DGQuotientModule), -- Minimize the
        presentation of a DG quotient module
      * prune(DGQuotientModule) -- Minimize
        the presentation of a DG quotient module
      * "minimalPresentation(DGSubmodule)" -- see prune(DGSubmodule),
        -- Trim a DG submodule to a minimal generating
        set of its inclusion
      * prune(DGSubmodule) -- Trim a DG
        submodule to a minimal generating set of its inclusion
      * QQ * DGModuleMap (missing documentation)
      * rank(DGModule) -- Rank of the underlying
        free A.natural-module
      * "rank(DGSubmodule)" -- see rank(DGModule), --
        Rank of the underlying free A.natural-module
      * "restrictDifferential(DGAlgebra,List)" -- see
        restrictDifferential, -- Synonym for
        subDGAlgebra, named to match the restricted-differential vocabulary
      * ring(DGAlgebra) (missing documentation)
      * ring(DGModule) (missing documentation)
      * ring(DGModuleMap) (missing documentation)
      * RingElement % DGIdeal -- Reduce a ring
        element modulo a DG ideal
      * "ZZ % DGIdeal" -- see RingElement % DGIdeal,
        -- Reduce a ring element modulo a DG ideal
      * RingElement * DGModuleMap (missing documentation)
      * "semifreeResolution(DGAlgebra,Module)" -- see semifreeResolution,
        -- Build a semifree DG module resolving a module
        over the base ring
      * "semifreeResolution(Module)" -- see semifreeResolution,
        -- Build a semifree DG module resolving a module
        over the base ring
      * "setDiff(DGAlgebra,List)" -- see setDiff, -- Install or
        replace the differential on a DG algebra
      * setDiff(DGModule,List) -- Install
        the list of generator differentials on a free DG module
      * source(DGAlgebraMap) -- The source of
        a DG algebra map
      * source(DGModuleMap) (missing documentation)
      * "subDGAlgebra(DGAlgebra,List)" -- see subDGAlgebra,
        -- The sub-DG algebra generated by a chosen subset of DG generators
      * "cover(DGQuotientModule)" -- see super(DGSubmodule),
        -- Ambient DGModule, cover, and relation matrix
        of a DG sub- or quotient module
      * "relations(DGQuotientModule)" -- see super(DGSubmodule),
        -- Ambient DGModule, cover, and relation matrix
        of a DG sub- or quotient module
      * "super(DGQuotientModule)" -- see super(DGSubmodule),
        -- Ambient DGModule, cover, and relation matrix
        of a DG sub- or quotient module
      * super(DGSubmodule) -- Ambient DGModule,
        cover, and relation matrix of a DG sub- or quotient module
      * target(DGAlgebraMap) -- The target of
        a DG algebra map
      * target(DGModuleMap) (missing documentation)
      * "toComplex(DGAlgebra)" -- see toComplex, -- Converts a
        DGAlgebra to a Complex
      * toComplex(DGAlgebra,ZZ), --
        Converts a DGAlgebra to a Complex
      * toComplex(DGIdeal) -- Export a DG ideal
        to a Complex (not yet implemented)
      * toComplex(DGModule) -- Export a DG
        module to a Complex of free base-ring modules
      * toComplex(DGModule,ZZ) -- Export a
        DG module to a Complex with an explicit hom-degree bound
      * toComplex(DGQuotientModule), --
        Export a DG quotient module to a Complex
      * "toComplexMap(DGAlgebraMap)" -- see toComplexMap,
        -- Construct the ComplexMap associated to a DGAlgebraMap
      * "toComplexMap(DGAlgebraMap,ZZ)" -- see toComplexMap,
        -- Construct the ComplexMap associated to a DGAlgebraMap
      * toComplexMap(DGModuleMap), --
        Export a DG module map to a ComplexMap
      * toComplexMap(DGModuleMap,ZZ),
        -- The per-hom-degree component of a DG module map as a matrix
      * "torAlgebra(Ring)" -- see torAlgebra, -- Computes the
        Tor algebra of a ring
      * torAlgebra(Ring,Ring) -- Computes
        Tor_R(S,k) up to a specified generating and relating degree.
      * "torMap(RingMap)" -- see torMap, -- Compute the map of
        Tor algebras associated to a RingMap.
      * "truncateGenerators(DGAlgebra,ZZ)" -- see truncateGenerators,
        -- Restrict a DG algebra to its generators of
        hom-degree strictly above a bound
      * "underlyingAlgebra(DGAlgebra)" -- see underlyingAlgebra,
        -- The graded-commutative algebra carrying the DG
        structure
      * "underlyingAlgebra(DGModule)" -- see underlyingAlgebra,
        -- The graded-commutative algebra carrying the DG
        structure
      * "underlyingRing(DGAlgebra)" -- see underlyingRing,
        -- The commutative base ring of a DG algebra or DG
        module
      * "underlyingRing(DGModule)" -- see underlyingRing,
        -- The commutative base ring of a DG algebra or DG module
      * "zeroDGModuleMap(DGModule,DGModule)" -- see zeroDGModuleMap,
        -- The zero DGModuleMap between two DG modules over a
        common algebra
      * "zerothHomology(DGAlgebra)" -- see zerothHomology,
        -- The zeroth homology of a DG algebra as a ring
      * ZZ * DGModuleMap (missing documentation)
      * ZZ == DGModuleMap (missing documentation)
  * Symbols
      * AssertWellDefined -- Option to verify that a
        constructed DG algebra map respects differentials
      * cycles -- Chosen cycle representatives for homology
        generators of a DG algebra
      * dgAlgebra (missing documentation)
      * EndDegree -- Option to specify the last homological
        degree processed by an iterative DG construction
      * GenDegreeLimit -- Option to bound the
        homological degree searched for algebra generators
      * natural -- The underlying graded-commutative ring of a
        DGAlgebra or DGModule
      * RelDegreeLimit -- Option to bound the
        homological degree searched for algebra relations
      * ringMap -- The degree-zero ring map underlying a
        DGAlgebraMap
      * "InitializeComplex" -- see setDiff, -- Install or
        replace the differential on a DG algebra
      * "InitializeDegreeZeroHomology" -- see setDiff, --
        Install or replace the differential on a DG algebra
      * StartDegree -- Option to specify the first
        homological degree processed by an iterative DG construction
      * TMOLimit -- Option to bound the arity of Massey
        operations searched for by findTrivialMasseyOperation

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

The object DGAlgebras, is a package (Macaulay2Doc),
defined in DGAlgebras.m2, with auxiliary files in DGAlgebras/.

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:32:0.

Basic operations on DG Algebras -- Outlines some basic operations on DG Algebras
********************************************************************************

There are several ways to define a DGAlgebra.  One can start by defining one
'from scratch'.  One does this by specifying the ring over which the DGAlgebra
is defined and the degrees of the generators.  The name of the generators of
the DGAlgebra by default is $T_i$, but one may change this by specifying the
optional (string) argument 'Variable'.

+---------------------------------------------------+
|i1 : R = ZZ/101[a,b,c,d]/ideal{a^3,b^3,c^3,d^3}    |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : QuotientRing                                  |
+---------------------------------------------------+
|i2 : A = freeDGAlgebra(R,{{1,1},{1,1},{1,1},{1,1}})|
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,4           |
|      Differential => null                         |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+

The command freeDGAlgebra only defines the underlying algebra of A, and not the
differential.  To set the differential of A, one uses the command setDiff.

+------------------------------------------+
|i3 : setDiff(A, gens R)                   |
|                                          |
|o3 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,4  |
|      Differential => {a, b, c, d}        |
|                                          |
|o3 : DGAlgebra                            |
+------------------------------------------+

Note that the above is the (graded) Koszul complex on a set of generators of R.
A much easier way to define this is to use the function koszulComplexDGA.

+-------------------------------------------+
|i4 : B = koszulComplexDGA(R, Variable=>"S")|
|                                           |
|o4 = {Ring => R                          } |
|      Underlying algebra => R[S   ..S   ]  |
|                               1,1   1,4   |
|      Differential => {a, b, c, d}         |
|                                           |
|o4 : DGAlgebra                             |
+-------------------------------------------+

One can compute the homology algebra of a DGAlgebra using the homology (or HH)
command.

+-----------------------------------------------------------------------------+
|i5 : HB = HH B                                                               |
|Finding easy relations           :  -- used 0.0231442s (cpu); 0.0222243s     |
|                                                                             |
|o5 = HB                                                                      |
|                                                                             |
|o5 : PolynomialRing, 4 skew commutative variable(s)                          |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i6 : describe HB                                                             |
|                                                                             |
|      ZZ                                                                     |
|o6 = ---[X ..X , Degrees => {4:{1}}, Heft => {1, 0}, Join => false,          |
|     101  1   4                {3}                                           |
|-----------------------------------------------------------------------------|
|SkewCommutative => {0..3}]                                                   |
+-----------------------------------------------------------------------------+
|i7 : degrees HB                                                              |
|                                                                             |
|o7 = {{1, 3}, {1, 3}, {1, 3}, {1, 3}}                                        |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+

Note that since R is a complete intersection, its Koszul homology algebra is an
exterior algebra, which is a free graded commutative algebra.  Note that the
internal degree is preserved in the computation of the homology algebra of B.

One can also adjoin variables to kill cycles in homology.  The command
killCycles looks for the first positive degree nonzero homology (say i), and
adjoins variables in homological degree i+1 that differentiate to a minimal
generating set of this homology, so that the resulting DGAlgebra now only has
homology in degree greater than i (note of course this could introduce new
homology in higher degrees). The command adjoinVariables allows finer control
over this procedure.  See adjoinVariables, for an
example.

+-----------------------------------------------------------------------------+
|i8 : HB.cache.cycles                                                         |
|                                                                             |
|       2       2       2       2                                             |
|o8 = {a S   , b S   , c S   , d S   }                                        |
|         1,1     1,2     1,3     1,4                                         |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
|i9 : C = adjoinVariables(B,{first HB.cache.cycles})                          |
|                                                                             |
|o9 = {Ring => R                                }                             |
|      Underlying algebra => R[S   ..S   , S   ]                              |
|                               1,1   1,4   2,1                               |
|                                    2                                        |
|      Differential => {a, b, c, d, a S   }                                   |
|                                      1,1                                    |
|                                                                             |
|o9 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i10 : homologyAlgebra(C,GenDegreeLimit=>4,RelDegreeLimit=>4)                 |
|Finding easy relations           :  -- used 0.0264839s (cpu); 0.0250487s     |
|                                                                             |
|       ZZ                                                                    |
|o10 = ---[X ..X ]                                                            |
|      101  1   3                                                             |
|                                                                             |
|o10 : PolynomialRing, 3 skew commutative variable(s)                         |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i11 : C = killCycles(B)                                                      |
|                                                                             |
|o11 = {Ring => R                                                   }         |
|       Underlying algebra => R[S   ..S   ]                                   |
|                                1,1   2,4                                    |
|                                     2       2       2       2               |
|       Differential => {a, b, c, d, a S   , b S   , c S   , d S   }          |
|                                       1,1     1,2     1,3     1,4           |
|                                                                             |
|o11 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i12 : homologyAlgebra(C,GenDegreeLimit=>4,RelDegreeLimit=>4)                 |
|                                                                             |
|       ZZ                                                                    |
|o12 = ---                                                                    |
|      101                                                                    |
|                                                                             |
|o12 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+

Again, note that since R is a complete intersection, once we adjoin the
variables in homological degree two to kill the cycles in degree one, we obtain
a minimal DG Algebra resolution of the residue field of R.  Also, note that
since C has generators in even degree, one must specify the optional arguments
GenDegreeLimit and RelDegreeLimit to specify the max degree of the computation.
To do this, one uses the homologyAlgebra command rather than the HH command.

This computation could have also been done with the command acyclicClosure.
The command acyclicClosure performs the command killCycles sequentially to
ensure that the result has homology in higher and higher degrees, thereby
computing (part of) a minimal DG Algebra resolution of the residue field.
acyclicClosure has an optional argument EndDegree that allows the user to
specify the maximum homological degree with which to perform this adjunction of
variables.  The default value of this is 3, since if there are any variables of
degree 3 that need to be added, then each subsequent homological degree will
require some variables to be adjoined (Halperin's rigidity theorem).

+-----------------------------------------------------------------------------+
|i13 : D = acyclicClosure R                                                   |
|                                                                             |
|o13 = {Ring => R                                                   }         |
|       Underlying algebra => R[T   ..T   ]                                   |
|                                1,1   2,4                                    |
|                                     2       2       2       2               |
|       Differential => {a, b, c, d, a T   , b T   , c T   , d T   }          |
|                                       1,1     1,2     1,3     1,4           |
|                                                                             |
|o13 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i14 : R' = ZZ/101[x,y,z]/ideal{x^2,y^2,z^2,x*y*z}                            |
|                                                                             |
|o14 = R'                                                                     |
|                                                                             |
|o14 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i15 : E = acyclicClosure(R',EndDegree=>5)                                    |
|                                                                             |
|o15 = {Ring => R'                                                            |
|       Underlying algebra => R'[T   ..T   , T   ..T   , T   ..T   , T   ..T  |
|                                 1,1   1,3   2,1   2,4   3,1   3,3   4,1   4,|
|                                                                             |
|       Differential => {x, y, z, x*T   , y*T   , z*T   , y*z*T   , y*z*T   , |
|                                    1,1     1,2     1,3       1,1       2,1  |
|                                                                             |
|o15 : DGAlgebra                                                              |
|-----------------------------------------------------------------------------|
|                                                                             |
| , T   ..T    , T   ..T    ]                                                 |
|6   5,1   5,13   6,1   6,27                                                  |
|                                                                             |
|-y*z*T   T   , -y*z*T   T   , -y*z*T   T   , -y*z*T   T   , y*z*T   T   ,    |
|      1,1 1,3        1,1 1,2        1,1 2,2        1,1 2,3       1,3 2,1     |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                     2                       |
|y*z*T   T   , y*z*T   T   , -y*z*T   T   T   , -y*z*T   , -y*z*T   T   ,     |
|     1,2 2,1       1,1 2,1        1,1 1,2 1,3        2,1        2,1 2,2      |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|-y*z*T   T   , y*z*T   T   T   , y*z*T   T   T   , y*z*T   T   T   ,         |
|      2,1 2,3       1,1 1,3 2,2       1,1 1,2 2,2       1,1 1,3 2,3          |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|y*z*T   T   T   , -y*z*T   T   T   , -y*z*T   T   T   , -y*z*T   T   T   ,   |
|     1,1 1,2 2,3        1,2 1,3 2,1        1,1 1,3 2,1        1,1 1,2 2,1    |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                            2                |
|-y*z*T   T   , y*z*T   T   T   , y*z*T   T   T   , y*z*T   T   ,             |
|      2,1 2,4       1,1 1,3 2,4       1,1 1,2 2,4       1,1 2,2              |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                           2              2              2              2    |
|y*z*T   T   T   , y*z*T   T   , -y*z*T   T   , -y*z*T   T   , -y*z*T   T   , |
|     1,1 2,2 2,3       1,1 2,3        1,3 2,1        1,2 2,1        1,1 2,1  |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|-y*z*T   T   T   , -y*z*T   T   T   , -y*z*T   T   T   , -y*z*T   T   T   ,  |
|      1,3 2,1 2,2        1,2 2,1 2,2        1,1 2,1 2,2        1,3 2,1 2,3   |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|-y*z*T   T   T   , -y*z*T   T   T   , y*z*T   T   T   T   ,                  |
|      1,2 2,1 2,3        1,1 2,1 2,3       1,1 1,2 1,3 2,2                   |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|y*z*T   T   T   T   , -y*z*T   T   T   T   , y*z*T   T   , -y*z*T   T   T   ,|
|     1,1 1,2 1,3 2,3        1,1 1,2 1,3 2,1       2,1 3,1        1,1 1,3 3,1 |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|-y*z*T   T   T   , -y*z*T   T   T   , - y*z*T   T   T   T    -               |
|      1,1 1,3 3,2        1,1 1,2 3,1         1,1 1,2 1,3 2,4                 |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|y*z*T   T   T   , -y*z*T   T   T   , y*z*T   T   T   , y*z*T   T   T   ,     |
|     1,1 1,2 3,2        1,1 1,2 3,3       1,1 2,2 2,4       1,1 2,3 2,4      |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|-y*z*T   T   T   , -y*z*T   T   T   , -y*z*T   T   T   ,                     |
|      1,3 2,1 2,4        1,2 2,1 2,4        1,1 2,1 2,4                      |
|-----------------------------------------------------------------------------|
|                     }                                                       |
|                                                                             |
|                                                                             |
|                                                                             |
|y*z*T   T   T   T   }                                                        |
|     1,1 1,2 1,3 2,4                                                         |
+-----------------------------------------------------------------------------+
|i16 : tally degrees E.natural                                                |
|                                                                             |
|o16 = Tally{{1, 1} => 3 }                                                    |
|            {2, 2} => 3                                                      |
|            {2, 3} => 1                                                      |
|            {3, 4} => 3                                                      |
|            {4, 5} => 6                                                      |
|            {5, 6} => 10                                                     |
|            {5, 7} => 3                                                      |
|            {6, 7} => 15                                                     |
|            {6, 8} => 12                                                     |
|                                                                             |
|o16 : Tally                                                                  |
+-----------------------------------------------------------------------------+

As you can see, since R' is not a complete intersection, the acyclic closure of
E requires infinitely many variables; we display the degrees of the first 6
here. The tally that is displayed gives the deviations of the ring R.  One can
compute the deviations directly from any minimal free resolution of the residue
field of R', so that using the one provided by res coker vars R is faster.  To
do this, use the command deviations.

+-----------------------------------+
|i17 : deviations(R,DegreeLimit=>6) |
|                                   |
|o17 = HashTable{(1, {1}) => 4}     |
|                (2, {3}) => 4      |
|                                   |
|o17 : HashTable                    |
+-----------------------------------+
|i18 : deviations(R',DegreeLimit=>6)|
|                                   |
|o18 = HashTable{(1, {1}) => 3 }    |
|                (2, {2}) => 3      |
|                (2, {3}) => 1      |
|                (3, {4}) => 3      |
|                (4, {5}) => 6      |
|                (5, {6}) => 10     |
|                (5, {7}) => 3      |
|                (6, {7}) => 15     |
|                (6, {8}) => 12     |
|                                   |
|o18 : HashTable                    |
+-----------------------------------+

As a brief warning, the command poincareN (Macaulay2Doc), which
is used in deviations, uses the symbols S and T internally,
and may cause problems referring to such rings at the Macaulay2 prompt.

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:103:0.

The Koszul complex as a DG Algebra -- an example
************************************************

The Koszul complex on a sequence of elements $f_1,\dots,f_r$ is a complex of
R-modules whose underlying graded R-module is the exterior algebra on R^r
generated in homological degree one.  This algebra structure also respects the
boundary map of the complex in the sense that it satisfies the Leibniz rule.
That is, $d(ab) = d(a)b + (-1)^{deg a}ad(b)$.  When one speaks of 'the' Koszul
complex of a ring, one means the Koszul complex on a minimal set of generators
of the maximal ideal of R.

+-----------------------------------------------+
|i1 : R = ZZ/101[a,b,c,d]/ideal{a^3,b^3,c^3,d^3}|
|                                               |
|o1 = R                                         |
|                                               |
|o1 : QuotientRing                              |
+-----------------------------------------------+
|i2 : KR = koszulComplexDGA R                   |
|                                               |
|o2 = {Ring => R                          }     |
|      Underlying algebra => R[T   ..T   ]      |
|                               1,1   1,4       |
|      Differential => {a, b, c, d}             |
|                                               |
|o2 : DGAlgebra                                 |
+-----------------------------------------------+

One can specify the name of the variable to easily handle multiple Koszul
complexes at once.

+---------------------------------------------------------+
|i3 : S = ZZ/101[x,y,z]/ideal{x^3,y^3,z^3,x^2*y^2,y^2*z^2}|
|                                                         |
|o3 = S                                                   |
|                                                         |
|o3 : QuotientRing                                        |
+---------------------------------------------------------+
|i4 : KS = koszulComplexDGA(S,Variable=>"U")              |
|                                                         |
|o4 = {Ring => S                          }               |
|      Underlying algebra => S[U   ..U   ]                |
|                               1,1   1,3                 |
|      Differential => {x, y, z}                          |
|                                                         |
|o4 : DGAlgebra                                           |
+---------------------------------------------------------+

To obtain the chain complex associated to the Koszul complex, one may use
toComplex.  One can also obtain this complex directly without using the
DGAlgebras package by using the command koszul (Macaulay2Doc).

+-----------------------------------------------------------------------------+
|i5 : cxKR = toComplex KR                                                     |
|                                                                             |
|      1      4      6      4      1                                          |
|o5 = R  <-- R  <-- R  <-- R  <-- R                                           |
|                                                                             |
|     0      1      2      3      4                                           |
|                                                                             |
|o5 : Complex                                                                 |
+-----------------------------------------------------------------------------+
|i6 : prune HH cxKR                                                           |
|                                                                             |
|o6 = cokernel | d c b a | <-- cokernel {3} | d c b a 0 0 0 0 0 0 0 0 0 0 0 0 |
|                                       {3} | 0 0 0 0 d c b a 0 0 0 0 0 0 0 0 |
|     0                                 {3} | 0 0 0 0 0 0 0 0 d c b a 0 0 0 0 |
|                                       {3} | 0 0 0 0 0 0 0 0 0 0 0 0 d c b a |
|                                                                             |
|                              1                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|o6 : Complex                                                                 |
|-----------------------------------------------------------------------------|
|| <-- cokernel {6} | d c b a 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 | <--   |
||              {6} | 0 0 0 0 d c b a 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 |       |
||              {6} | 0 0 0 0 0 0 0 0 d c b a 0 0 0 0 0 0 0 0 0 0 0 0 |       |
||              {6} | 0 0 0 0 0 0 0 0 0 0 0 0 d c b a 0 0 0 0 0 0 0 0 |       |
|               {6} | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 d c b a 0 0 0 0 |       |
|               {6} | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 d c b a |       |
|                                                                             |
|      2                                                                      |
|-----------------------------------------------------------------------------|
|cokernel {9} | d c b a 0 0 0 0 0 0 0 0 0 0 0 0 | <-- cokernel {12} | d c b a |
|         {9} | 0 0 0 0 d c b a 0 0 0 0 0 0 0 0 |                             |
|         {9} | 0 0 0 0 0 0 0 0 d c b a 0 0 0 0 |     4                       |
|         {9} | 0 0 0 0 0 0 0 0 0 0 0 0 d c b a |                             |
|                                                                             |
|3                                                                            |
|-----------------------------------------------------------------------------|
||                                                                            |
+-----------------------------------------------------------------------------+

Since the Koszul complex is a DG algebra, its homology is itself an algebra.
One can obtain this algebra using the command homology, homologyAlgebra, or HH
(all commands work).  This algebra structure can detect whether or not the ring
is a complete intersection or Gorenstein.

+-----------------------------------------------------------------------------+
|i7 : HKR = HH KR                                                             |
|Finding easy relations           :  -- used 0.0225831s (cpu); 0.0214066s     |
|                                                                             |
|o7 = HKR                                                                     |
|                                                                             |
|o7 : PolynomialRing, 4 skew commutative variable(s)                          |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i8 : ideal HKR                                                               |
|                                                                             |
|o8 = ideal ()                                                                |
|                                                                             |
|o8 : Ideal of HKR                                                            |
+-----------------------------------------------------------------------------+
|i9 : R' = ZZ/101[a,b,c,d]/ideal{a^3,b^3,c^3,d^3,a*c,a*d,b*c,b*d,a^2*b^2-c^2*d|
|                                                                             |
|o9 = R'                                                                      |
|                                                                             |
|o9 : QuotientRing                                                            |
|-----------------------------------------------------------------------------|
|^2}                                                                          |
+-----------------------------------------------------------------------------+
|i10 : HKR' = HH koszulComplexDGA R'                                          |
|Finding easy relations           :  -- used 1.08196s (cpu); 0.92588s         |
|                                                                             |
|o10 = HKR'                                                                   |
|                                                                             |
|o10 : QuotientRing                                                           |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i11 : numgens HKR'                                                           |
|                                                                             |
|o11 = 34                                                                     |
+-----------------------------------------------------------------------------+
|i12 : ann ideal gens HKR'                                                    |
|                                                                             |
|o12 = ideal(X X  )                                                           |
|             4 34                                                            |
|                                                                             |
|o12 : Ideal of HKR'                                                          |
+-----------------------------------------------------------------------------+

Note that since the socle of HKR' is one dimensional, HKR' has Poincare
duality, and hence R' is Gorenstein.

One can also consider the Koszul complex of an ideal, or a sequence of
elements.

+-----------------------------------------------------------------------------+
|i13 : Q = ambient R                                                          |
|                                                                             |
|o13 = Q                                                                      |
|                                                                             |
|o13 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i14 : I = ideal {a^3,b^3,c^3,d^3}                                            |
|                                                                             |
|              3   3   3   3                                                  |
|o14 = ideal (a , b , c , d )                                                 |
|                                                                             |
|o14 : Ideal of Q                                                             |
+-----------------------------------------------------------------------------+
|i15 : KI = koszulComplexDGA I                                                |
|                                                                             |
|o15 = {Ring => Q                          }                                  |
|       Underlying algebra => Q[T   ..T   ]                                   |
|                                1,1   1,4                                    |
|                         3   3   3   3                                       |
|       Differential => {a , b , c , d }                                      |
|                                                                             |
|o15 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i16 : HKI = HH KI                                                            |
|                                                                             |
|o16 = HKI                                                                    |
|                                                                             |
|o16 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i17 : describe HKI                                                           |
|                                                                             |
|              Q                                                              |
|o17 = ----------------                                                       |
|        3   3   3   3                                                        |
|      (d , c , b , a )                                                       |
+-----------------------------------------------------------------------------+
|i18 : use Q                                                                  |
|                                                                             |
|o18 = Q                                                                      |
|                                                                             |
|o18 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i19 : I' = I + ideal{a^2*b^2*c^2*d^2}                                        |
|                                                                             |
|              3   3   3   3   2 2 2 2                                        |
|o19 = ideal (a , b , c , d , a b c d )                                       |
|                                                                             |
|o19 : Ideal of Q                                                             |
+-----------------------------------------------------------------------------+
|i20 : KI' = koszulComplexDGA I'                                              |
|                                                                             |
|o20 = {Ring => Q                                 }                           |
|       Underlying algebra => Q[T   ..T   ]                                   |
|                                1,1   1,5                                    |
|                         3   3   3   3   2 2 2 2                             |
|       Differential => {a , b , c , d , a b c d }                            |
|                                                                             |
|o20 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i21 : HKI' = HH KI'                                                          |
|                                                                             |
|o21 = HKI'                                                                   |
|                                                                             |
|o21 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i22 : describe HKI'                                                          |
|                                                                             |
|                                                                       Q     |
|                                                          -------------------|
|                                                            3   3   3   3   2|
|                                                          (d , c , b , a , a |
|o22 = -----------------------------------------------------------------------|
|        2                  2                               2                 |
|      (a X , a*X  - b*X , b X , b*X  - c*X , a*X  - c*X , c X , c*X  - d*X , |
|          4     3      4     3     2      3     2      4     2     1      2  |
|-----------------------------------------------------------------------------|
|-------[X ..X ]                                                              |
| 2 2 2   1   4                                                               |
|b c d )                                                                      |
|-------------------------------------------------------------------          |
|                           2                                                 |
|b*X  - d*X , a*X  - d*X , d X , X X , X X , X X , X X , X X , X X )          |
|   1      3     1      4     1   3 4   2 4   1 4   2 3   1 3   1 2           |
+-----------------------------------------------------------------------------+
|i23 : HKI'.cache.cycles                                                      |
|                                                                             |
|        2 2 2                2 2 2                2 2 2                      |
|o23 = {a b c T    - d*T   , a b d T    - c*T   , a c d T    - b*T   ,        |
|              1,4      1,5         1,3      1,5         1,2      1,5         |
|      -----------------------------------------------------------------------|
|       2 2 2                                                                 |
|      b c d T    - a*T   }                                                   |
|             1,1      1,5                                                    |
|                                                                             |
|o23 : List                                                                   |
+-----------------------------------------------------------------------------+

Note that since I is a Q-regular sequence, the Koszul complex is acyclic, and
that both homology algebras are algebras over the zeroth homology of the Koszul
complex.

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:160:0.

Basic operations on DG Algebra Maps -- Outlines some basic operations on DGAlgebraMaps
**************************************************************************************

An algebra map between the underlying graded algebras that satisfies the
Leibniz rule is a morphism of DG algebras.  Such objects are created using the
DGAlgebraMap class.  As with DGAlgebras, one can define a DGAlgebraMap 'from
scratch' using dgAlgebraMap.

+-----------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c]/ideal{a^3+b^3+c^3,a*b*c}                  |
|                                                                 |
|o1 = R                                                           |
|                                                                 |
|o1 : QuotientRing                                                |
+-----------------------------------------------------------------+
|i2 : K1 = koszulComplexDGA(ideal vars R,Variable=>"Y")           |
|                                                                 |
|o2 = {Ring => R                          }                       |
|      Underlying algebra => R[Y   ..Y   ]                        |
|                               1,1   1,3                         |
|      Differential => {a, b, c}                                  |
|                                                                 |
|o2 : DGAlgebra                                                   |
+-----------------------------------------------------------------+
|i3 : K2 = koszulComplexDGA(ideal {b,c},Variable=>"T")            |
|                                                                 |
|o3 = {Ring => R                          }                       |
|      Underlying algebra => R[T   ..T   ]                        |
|                               1,1   1,2                         |
|      Differential => {b, c}                                     |
|                                                                 |
|o3 : DGAlgebra                                                   |
+-----------------------------------------------------------------+
|i4 : f = dgAlgebraMap(K2,K1,matrix{{0,T_(1,1),T_(1,2)}})         |
|                                                                 |
|o4 = map (R[T   ..T   ], R[Y   ..Y   ], {0, T   , T   , a, b, c})|
|             1,1   1,2      1,1   1,3        1,1   1,2           |
|                                                                 |
|o4 : DGAlgebraMap                                                |
+-----------------------------------------------------------------+

Once we define the DGAlgebraMap, it is a good idea to check to see if it indeed
satisfies the Leibniz rule.  This can be checked by using isWellDefined.

+--------------------+
|i5 : isWellDefined f|
|                    |
|o5 = false          |
+--------------------+

Oops!  Let's try that again.

+--------------------------------------------------------------+
|i6 : g = dgAlgebraMap(K1,K2,matrix{{Y_(1,2),Y_(1,3)}})        |
|                                                              |
|o6 = map (R[Y   ..Y   ], R[T   ..T   ], {Y   , Y   , a, b, c})|
|             1,1   1,3      1,1   1,2     1,2   1,3           |
|                                                              |
|o6 : DGAlgebraMap                                             |
+--------------------------------------------------------------+
|i7 : isWellDefined g                                          |
|                                                              |
|o7 = true                                                     |
+--------------------------------------------------------------+

One can lift a ring homomorphism in degree zero to a map of DGAlgebras (up to a
specified degree) using liftToDGMap.  This is helpful in some of the internal
functions of the DGAlgebras package, such as computing the map induced on Tor
algebras by a RingMap.

+-----------------------------------------------------------------------------+
|i8 : R = ZZ/101[a,b,c]/ideal{a^3,b^3,c^3}                                    |
|                                                                             |
|o8 = R                                                                       |
|                                                                             |
|o8 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i9 : S = R/ideal{a^2*b^2*c^2}                                                |
|                                                                             |
|o9 = S                                                                       |
|                                                                             |
|o9 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i10 : f = map(S,R)                                                           |
|                                                                             |
|o10 = map (S, R, {a, b, c})                                                  |
|                                                                             |
|o10 : RingMap S <-- R                                                        |
+-----------------------------------------------------------------------------+
|i11 : A = acyclicClosure(R,EndDegree=>3)                                     |
|                                                                             |
|o11 = {Ring => R                                        }                    |
|       Underlying algebra => R[T   ..T   ]                                   |
|                                1,1   2,3                                    |
|                                  2       2       2                          |
|       Differential => {a, b, c, a T   , b T   , c T   }                     |
|                                    1,1     1,2     1,3                      |
|                                                                             |
|o11 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i12 : B = acyclicClosure(S,EndDegree=>3)                                     |
|                                                                             |
|o12 = {Ring => S                                                             |
|       Underlying algebra => S[T   ..T   , T   ..T   , T   ..T   , T   ..T   |
|                                1,1   1,3   2,1   2,4   3,1   3,3   4,1   4,6|
|                                  2       2       2         2 2       2 2    |
|       Differential => {a, b, c, a T   , b T   , c T   , a*b c T   , b c T   |
|                                    1,1     1,2     1,3         1,1       2,1|
|                                                                             |
|o12 : DGAlgebra                                                              |
|-----------------------------------------------------------------------------|
|                                                                             |
|]                                                                            |
|                                                                             |
|    2 2        2 2       2 2            2 2           2 2                    |
|, -a b T   , -a c T   , b c T   T   , -a c T   T   , b c T   T   ,           |
|        2,3        2,2       1,3 2,1        1,3 2,2       1,2 2,1            |
|-----------------------------------------------------------------------------|
|                                    }                                        |
|                                                                             |
|                                                                             |
|  2           2           2                                                  |
|-a T   T   , c T   T   , b T   T   }                                         |
|    1,1 2,4     1,3 2,4     1,2 2,4                                          |
+-----------------------------------------------------------------------------+
|i13 : phi = liftToDGMap(B,A,f)                                               |
|                                                                             |
|o13 = map (S[T   ..T   , T   ..T   , T   ..T   , T   ..T   ], R[T   ..T   ], |
|              1,1   1,3   2,1   2,4   3,1   3,3   4,1   4,6      1,1   2,3   |
|                                                                             |
|o13 : DGAlgebraMap                                                           |
|-----------------------------------------------------------------------------|
|{T   , T   , T   , T   , T   , T   , a, b, c})                               |
|  1,1   1,2   1,3   2,1   2,2   2,3                                          |
+-----------------------------------------------------------------------------+

Once one has a DGAlgebraMap, one can also obtain the underlying map of
complexes via toComplexMap.

+-----------------------------------------------------------------------------+
|i14 : cmPhi = toComplexMap(phi,EndDegree=>3)                                 |
|                                                                             |
|                                          1                                  |
|o14 = 0 : cokernel | a2b2c2 | <--------- R  : 0                              |
|                                 | 1 |                                       |
|                                                                             |
|                                                                    3        |
|      1 : cokernel {1} | a2b2c2 0      0      | <----------------- R  : 1    |
|                   {1} | 0      a2b2c2 0      |    {1} | 1 0 0 |             |
|                   {1} | 0      0      a2b2c2 |    {1} | 0 1 0 |             |
|                                                   {1} | 0 0 1 |             |
|                                                                             |
|                                                                             |
|      2 : cokernel {2} | a2b2c2 0      0      0      0      0      0         |
|                   {2} | 0      a2b2c2 0      0      0      0      0         |
|                   {2} | 0      0      a2b2c2 0      0      0      0         |
|                   {3} | 0      0      0      a2b2c2 0      0      0         |
|                   {3} | 0      0      0      0      a2b2c2 0      0         |
|                   {3} | 0      0      0      0      0      a2b2c2 0         |
|                   {6} | 0      0      0      0      0      0      a2b2c2    |
|                                                                             |
|                                                                             |
|                                                                             |
|      3 : cokernel {3} | a2b2c2 0      0      0      0      0      0         |
|                   {4} | 0      a2b2c2 0      0      0      0      0         |
|                   {4} | 0      0      a2b2c2 0      0      0      0         |
|                   {4} | 0      0      0      a2b2c2 0      0      0         |
|                   {4} | 0      0      0      0      a2b2c2 0      0         |
|                   {4} | 0      0      0      0      0      a2b2c2 0         |
|                   {4} | 0      0      0      0      0      0      a2b2c2    |
|                   {4} | 0      0      0      0      0      0      0         |
|                   {4} | 0      0      0      0      0      0      0         |
|                   {4} | 0      0      0      0      0      0      0         |
|                   {7} | 0      0      0      0      0      0      0         |
|                   {7} | 0      0      0      0      0      0      0         |
|                   {7} | 0      0      0      0      0      0      0         |
|                   {7} | 0      0      0      0      0      0      0         |
|                   {7} | 0      0      0      0      0      0      0         |
|                   {7} | 0      0      0      0      0      0      0         |
|                                                                             |
|                                                                             |
|o14 : ComplexMap                                                             |
|-----------------------------------------------------------------------------|
|                            6                                                |
|| <----------------------- R  : 2                                            |
||    {2} | 1 0 0 0 0 0 |                                                     |
||    {2} | 0 1 0 0 0 0 |                                                     |
||    {2} | 0 0 1 0 0 0 |                                                     |
||    {3} | 0 0 0 1 0 0 |                                                     |
||    {3} | 0 0 0 0 1 0 |                                                     |
||    {3} | 0 0 0 0 0 1 |                                                     |
|     {6} | 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      |             |
|a2b2c2 0      0      0      0      0      0      0      0      |             |
|0      a2b2c2 0      0      0      0      0      0      0      |             |
|0      0      a2b2c2 0      0      0      0      0      0      |             |
|0      0      0      a2b2c2 0      0      0      0      0      |             |
|0      0      0      0      a2b2c2 0      0      0      0      |             |
|0      0      0      0      0      a2b2c2 0      0      0      |             |
|0      0      0      0      0      0      a2b2c2 0      0      |             |
|0      0      0      0      0      0      0      a2b2c2 0      |             |
|0      0      0      0      0      0      0      0      a2b2c2 |             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                  10                                         |
|<------------------------------- R   : 3                                     |
|   {3} | 1 0 0 0 0 0 0 0 0 0 |                                               |
|   {4} | 0 1 0 0 0 0 0 0 0 0 |                                               |
|   {4} | 0 0 1 0 0 0 0 0 0 0 |                                               |
|   {4} | 0 0 0 1 0 0 0 0 0 0 |                                               |
|   {4} | 0 0 0 0 1 0 0 0 0 0 |                                               |
|   {4} | 0 0 0 0 0 1 0 0 0 0 |                                               |
|   {4} | 0 0 0 0 0 0 1 0 0 0 |                                               |
|   {4} | 0 0 0 0 0 0 0 1 0 0 |                                               |
|   {4} | 0 0 0 0 0 0 0 0 1 0 |                                               |
|   {4} | 0 0 0 0 0 0 0 0 0 1 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
+-----------------------------------------------------------------------------+

There are also some auxiliary commands associated with DGAlgebraMaps

+-----------------------------------------------------------------------------+
|i15 : source phi                                                             |
|                                                                             |
|o15 = {Ring => R                                        }                    |
|       Underlying algebra => R[T   ..T   ]                                   |
|                                1,1   2,3                                    |
|                                  2       2       2                          |
|       Differential => {a, b, c, a T   , b T   , c T   }                     |
|                                    1,1     1,2     1,3                      |
|                                                                             |
|o15 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i16 : target phi                                                             |
|                                                                             |
|o16 = {Ring => S                                                             |
|       Underlying algebra => S[T   ..T   , T   ..T   , T   ..T   , T   ..T   |
|                                1,1   1,3   2,1   2,4   3,1   3,3   4,1   4,6|
|                                  2       2       2         2 2       2 2    |
|       Differential => {a, b, c, a T   , b T   , c T   , a*b c T   , b c T   |
|                                    1,1     1,2     1,3         1,1       2,1|
|                                                                             |
|o16 : DGAlgebra                                                              |
|-----------------------------------------------------------------------------|
|                                                                             |
|]                                                                            |
|                                                                             |
|    2 2        2 2       2 2            2 2           2 2                    |
|, -a b T   , -a c T   , b c T   T   , -a c T   T   , b c T   T   ,           |
|        2,3        2,2       1,3 2,1        1,3 2,2       1,2 2,1            |
|-----------------------------------------------------------------------------|
|                                    }                                        |
|                                                                             |
|                                                                             |
|  2           2           2                                                  |
|-a T   T   , c T   T   , b T   T   }                                         |
|    1,1 2,4     1,3 2,4     1,2 2,4                                          |
+-----------------------------------------------------------------------------+

One can also obtain the map on homology induced by a DGAlgebra map.

+-----------------------------------------------------------------------------+
|i17 : HHg = HH g                                                             |
|Finding easy relations           :  -- used 0.0200531s (cpu); 0.0191435s     |
|                                                                             |
|                          ZZ                                                 |
|                         ---[a..c]                                           |
|            ZZ           101                                                 |
|o17 = map (---[X ..X ], ----------[X ], {X , 0, 0, 0})                       |
|           101  1   2           3   1     1                                  |
|                        (c, b, a )                                           |
|                                                                             |
|                                ZZ                                           |
|                               ---[a..c]                                     |
|               ZZ              101                                           |
|o17 : RingMap ---[X ..X ] <-- ----------[X ]                                 |
|              101  1   2              3   1                                  |
|                              (c, b, a )                                     |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i18 : matrix HHg                                                             |
|                                                                             |
|o18 = | X_1 0 0 0 |                                                          |
|                                                                             |
|               ZZ         1       ZZ         4                               |
|o18 : Matrix (---[X ..X ])  <-- (---[X ..X ])                                |
|              101  1   2         101  1   2                                  |
+-----------------------------------------------------------------------------+
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:210:0.

Basic operations on DG Module Maps -- Outlines some basic operations on DGModuleMaps
************************************************************************************

A morphism of DG modules over a fixed DG algebra A is an A-linear map of
underlying graded A.natural-modules that commutes with the differentials.  Such
objects are created using the DGModuleMap class.  The workhorse constructor is
dgModuleMap, which accepts either a full Matrix encoding of
the map or a list of image Vectors (one per natural generator of the source).

+---------------------------------------------------------------+
|i1 : R = QQ[x,y]/ideal(x^2,y^2)                                |
|                                                               |
|o1 = R                                                         |
|                                                               |
|o1 : QuotientRing                                              |
+---------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                    |
|                                                               |
|o2 = {Ring => R                          }                     |
|      Underlying algebra => R[T   ..T   ]                      |
|                               1,1   1,2                       |
|      Differential => {x, y}                                   |
|                                                               |
|o2 : DGAlgebra                                                 |
+---------------------------------------------------------------+
|i3 : k = R^1 / ideal(x, y)                                     |
|                                                               |
|o3 = cokernel | x y |                                          |
|                                                               |
|                            1                                  |
|o3 : R-module, quotient of R                                   |
+---------------------------------------------------------------+
|i4 : Mdg = minimalSemifreeResolution(A, k, EndDegree => 2)     |
|                                                               |
|o4 = {Base ring => R                                          }|
|      DG algebra => R[T   ..T   ]                              |
|                       1,1   1,2                               |
|                                       3                       |
|      Natural module => (R[T   ..T   ])                        |
|                            1,1   1,2                          |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}}            |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |} |
|                                   |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |
|                                                               |
|o4 : DGModule                                                  |
+---------------------------------------------------------------+
|i5 : idM = identityDGModuleMap Mdg                             |
|                                                               |
|                               3                               |
|o5 = {Source => (R[T   ..T   ])  }                             |
|                    1,1   1,2                                  |
|                               3                               |
|      Target => (R[T   ..T   ])                                |
|                    1,1   1,2                                  |
|      Natural => {0, 0} | 1 0 0 |                              |
|                 {2, 2} | 0 1 0 |                              |
|                 {2, 2} | 0 0 1 |                              |
|                                                               |
|o5 : DGModuleMap                                               |
+---------------------------------------------------------------+
|i6 : isWellDefined idM                                         |
|                                                               |
|o6 = true                                                      |
+---------------------------------------------------------------+

As with DGAlgebraMaps, once you have a candidate map it is a good idea to check
isWellDefined (Macaulay2Doc).  The check verifies (per
natural generator of the source) both the hom-degree condition and the
chain-map condition $d_N \circ f = f \circ d_M$.

+-------------------------------------------------------------+
|i7 : natGens = apply(rank Mdg.natural, i -> (Mdg.natural)_i) |
|                                                             |
|o7 = {| 1 |, | 0 |, | 0 |}                                   |
|      | 0 |  | 1 |  | 0 |                                    |
|      | 0 |  | 0 |  | 1 |                                    |
|                                                             |
|o7 : List                                                    |
+-------------------------------------------------------------+
|i8 : xMap = dgModuleMap(Mdg, Mdg, apply(natGens, g -> x * g))|
|                                                             |
|                               3                             |
|o8 = {Source => (R[T   ..T   ])  }                           |
|                    1,1   1,2                                |
|                               3                             |
|      Target => (R[T   ..T   ])                              |
|                    1,1   1,2                                |
|      Natural => {0, 0} | x 0 0 |                            |
|                 {2, 2} | 0 x 0 |                            |
|                 {2, 2} | 0 0 x |                            |
|                                                             |
|o8 : DGModuleMap                                             |
+-------------------------------------------------------------+
|i9 : isWellDefined xMap                                      |
|                                                             |
|o9 = true                                                    |
+-------------------------------------------------------------+

A DGModuleMap induces a chain map between the underlying complexes via
toComplexMap, and a module map on every homology degree via
homology (Macaulay2Doc).

+----------------------------------------+
|i10 : H0 = homology(xMap, 0)            |
|                                        |
|o10 = 0                                 |
|                                        |
|o10 : Matrix k <-- k                    |
+----------------------------------------+
|i11 : H0 == map(target H0, source H0, 0)|
|                                        |
|o11 = true                              |
+----------------------------------------+

Classical construction: given a hom-degree-0 seed (the images of the hom-deg-0
generators of M in N.natural), see liftToDGModuleMap,
inductively solves $d_N(x) = f(d_M(e))$ degree by degree, producing a full
chain map M -> N. Requires N to be acyclic up to the requested EndDegree.

+------------------------------------------------------------------------+
|i12 : f = liftToDGModuleMap(Mdg, Mdg, {(Mdg.natural)_0}, EndDegree => 2)|
|                                                                        |
|                                3                                       |
|o12 = {Source => (R[T   ..T   ])  }                                     |
|                     1,1   1,2                                          |
|                                3                                       |
|       Target => (R[T   ..T   ])                                        |
|                     1,1   1,2                                          |
|       Natural => {0, 0} | 1 0 0 |                                      |
|                  {2, 2} | 0 1 0 |                                      |
|                  {2, 2} | 0 0 1 |                                      |
|                                                                        |
|o12 : DGModuleMap                                                       |
+------------------------------------------------------------------------+
|i13 : isWellDefined f                                                   |
|                                                                        |
|o13 = true                                                              |
+------------------------------------------------------------------------+
|i14 : h0 = homology(f, 0)                                               |
|                                                                        |
|o14 = | 1 |                                                             |
|                                                                        |
|o14 : Matrix k <-- k                                                    |
+------------------------------------------------------------------------+
|i15 : h0 == id_(source h0)                                              |
|                                                                        |
|o15 = true                                                              |
+------------------------------------------------------------------------+

Auxiliary operations: addition, subtraction, scalar multiplication by elements
of A.ring, negation, and composition via $*$ are all supported, mirroring the
matrix-level operations on f.natural.

+--------------------------------------------+
|i16 : (2_R * idM).natural == 2 * idM.natural|
|                                            |
|o16 = true                                  |
+--------------------------------------------+
|i17 : (idM * idM).natural == idM.natural    |
|                                            |
|o17 = true                                  |
+--------------------------------------------+

See also
========

  * DGModuleMap -- The class of morphisms of DG modules
    over a common DG algebra
  * dgModuleMap -- Construct a DGModuleMap from a matrix or
    from a list of image Vectors
  * identityDGModuleMap -- The identity DGModuleMap
    on a DG module
  * zeroDGModuleMap -- The zero DGModuleMap between two
    DG modules over a common algebra
  * liftToDGModuleMap -- Lift an image of
    hom-degree-0 generators to a full DGModuleMap
  * isWellDefined (Macaulay2Doc) -- whether a map is well
    defined
  * toComplexMap -- Construct the ComplexMap associated to
    a DGAlgebraMap
  * homology (Macaulay2Doc) -- general homology functor
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:272:0.

Base change and tensor with non-DG types -- Tensoring DG objects with ordinary rings and modules
************************************************************************************************

The DGAlgebras package extends **, so that every
DG object (see DGAlgebra, DGModule,
DGSubmodule, DGQuotientModule,
DGIdeal, DGAlgebraMap, DGModuleMap)
can be base-changed along any ring map out of the ground ring.
It also defines the exterior tensor of a DGModule with an ordinary
Module (Macaulay2Doc), subsuming the usual ring-of-scalars base change
as the special case M ** S^1.

Two design choices make these operations usable in larger constructions.

Caching (object identity).  Both DGAlgebra ** Ring,
and DGModule ** Ring, cache their result, so
repeated calls with the same operands return the SAME object.  This matters
because a DGAlgebraMap or DGModuleMap is tagged by its source and target
DG-objects, and without identity the source of id_M ** S and the target of id_M
** S would be two distinct (though isomorphic) DGModules.

Functoriality.  These operations are functorial: if id is the identity
DGModuleMap on M, then id ** S is the identity DGModuleMap on M ** S; likewise
for DGAlgebraMaps.  Composition is preserved.

+--------------------------------------------+
|i1 : R = ZZ/101[x,y]                        |
|                                            |
|o1 = R                                      |
|                                            |
|o1 : PolynomialRing                         |
+--------------------------------------------+
|i2 : A = koszulComplexDGA R                 |
|                                            |
|o2 = {Ring => R                          }  |
|      Underlying algebra => R[T   ..T   ]   |
|                               1,1   1,2    |
|      Differential => {x, y}                |
|                                            |
|o2 : DGAlgebra                              |
+--------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})            |
|                                            |
|o3 = {Base ring => R                       }|
|      DG algebra => R[T   ..T   ]           |
|                       1,1   1,2            |
|                                       2    |
|      Natural module => (R[T   ..T   ])     |
|                            1,1   1,2       |
|      Generator degrees => {{0, 0}, {1, 0}} |
|      Differentials on gens => {0, 0}       |
|                                            |
|o3 : DGModule                               |
+--------------------------------------------+
|i4 : QR = R / ideal(x^2)                    |
|                                            |
|o4 = QR                                     |
|                                            |
|o4 : QuotientRing                           |
+--------------------------------------------+
|i5 : MQ = M ** QR                           |
|                                            |
|o5 = {Base ring => QR                      }|
|      DG algebra => QR[T   ..T   ]          |
|                        1,1   1,2           |
|                                        2   |
|      Natural module => (QR[T   ..T   ])    |
|                             1,1   1,2      |
|      Generator degrees => {{0, 0}, {1, 0}} |
|      Differentials on gens => {0, 0}       |
|                                            |
|o5 : DGModule                               |
+--------------------------------------------+
|i6 : MQ === M ** QR                         |
|                                            |
|o6 = true                                   |
+--------------------------------------------+
|i7 : idM = identityDGModuleMap M            |
|                                            |
|                               2            |
|o7 = {Source => (R[T   ..T   ]) }           |
|                    1,1   1,2               |
|                               2            |
|      Target => (R[T   ..T   ])             |
|                    1,1   1,2               |
|      Natural => {0, 0} | 1 0 |             |
|                 {1, 0} | 0 1 |             |
|                                            |
|o7 : DGModuleMap                            |
+--------------------------------------------+
|i8 : (idM ** QR).source === MQ              |
|                                            |
|o8 = true                                   |
+--------------------------------------------+
|i9 : (idM ** QR).target === MQ              |
|                                            |
|o9 = true                                   |
+--------------------------------------------+
|i10 : isWellDefined(idM ** QR)              |
|                                            |
|o10 = true                                  |
+--------------------------------------------+

For a DGModule M and an ordinary free module N, M ** N forms the exterior
tensor product over A.natural.  This lets you tensor by copies of a ring, by
direct sums, or by arbitrary graded shifts without leaving the DG world.

+-------------------------------------------------------------+
|i11 : N = R^{0, -1}                                          |
|                                                             |
|       2                                                     |
|o11 = R                                                      |
|                                                             |
|o11 : R-module, free, degrees {0..1}                         |
+-------------------------------------------------------------+
|i12 : MN = M ** N                                            |
|                                                             |
|o12 = {Base ring => R                                       }|
|       DG algebra => R[T   ..T   ]                           |
|                        1,1   1,2                            |
|                                        4                    |
|       Natural module => (R[T   ..T   ])                     |
|                             1,1   1,2                       |
|       Generator degrees => {{0, 0}, {0, 1}, {1, 0}, {1, 1}} |
|       Differentials on gens => {0, 0, 0, 0}                 |
|                                                             |
|o12 : DGModule                                               |
+-------------------------------------------------------------+
|i13 : class MN                                               |
|                                                             |
|o13 = DGModule                                               |
|                                                             |
|o13 : Type                                                   |
+-------------------------------------------------------------+
|i14 : numgens MN                                             |
|                                                             |
|o14 = 4                                                      |
+-------------------------------------------------------------+
|i15 : rank MN.natural == (rank M.natural) * (rank N)         |
|                                                             |
|o15 = true                                                   |
+-------------------------------------------------------------+

The tensor is associative in the natural way: you can chain (M ** N) ** K for a
sequence of ordinary free modules, producing a DGModule whose natural rank is
the product of the ranks.

+-----------------------------------------------------------------------------+
|i16 : K = R^3                                                                |
|                                                                             |
|       3                                                                     |
|o16 = R                                                                      |
|                                                                             |
|o16 : R-module, free                                                         |
+-----------------------------------------------------------------------------+
|i17 : MNK = (M ** R^2) ** K                                                  |
|                                                                             |
|o17 = {Base ring => R                                                        |
|       DG algebra => R[T   ..T   ]                                           |
|                        1,1   1,2                                            |
|                                        12                                   |
|       Natural module => (R[T   ..T   ])                                     |
|                             1,1   1,2                                       |
|       Generator degrees => {{0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, |
|       Differentials on gens => {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}         |
|                                                                             |
|o17 : DGModule                                                               |
|-----------------------------------------------------------------------------|
|                                               }                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|{1, 0}, {1, 0}, {1, 0}, {1, 0}, {1, 0}, {1, 0}}                              |
+-----------------------------------------------------------------------------+
|i18 : isWellDefined MNK                                                      |
|                                                                             |
|o18 = true                                                                   |
+-----------------------------------------------------------------------------+
|i19 : numgens MNK == 2 * 2 * 3                                               |
|                                                                             |
|o19 = true                                                                   |
+-----------------------------------------------------------------------------+

A deliberate omission: there is no ** Ideal method.  For an ideal I, the
underlying module module I is almost never free, so exterior tensor with a
DGModule is not well-defined in our framework.  Use ** (R/I) for base change
along the quotient instead.

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1780:0.

DGAlgebra ** Ring -- Base change of a DG algebra to another ring
****************************************************************

  * Operator: ** (Macaulay2Doc),
  * Usage:
        B = A ** S
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * S, a ring (Macaulay2Doc), A ring that admits substitution
        from A.ring.  The common case is S = A.ring / I for some ideal I, but
        any ring into which the variables of A.natural substitute is allowed.
  * Outputs:
      * B, an instance of the type DGAlgebra, A DG algebra
        over S with the same generator degrees as A and with differential
        obtained by substituting every entry of the differential matrix of A
        into B.natural.

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

Base change: the underlying graded algebra is the same exterior / symmetric
shape over S, and the differential is transported by substitute (Macaulay2Doc).
When S = A.ring / I, this models the DG algebra "A
mod I" used, for instance, in building the Koszul complex of a quotient ring.

The result is cached on A.cache: repeated calls A ** S with the same pair (A,
S) return the SAME DGAlgebra object.  This identity is essential for
functoriality of base change on DGAlgebraMaps and DGModules — see Base change and tensor with non-DG types.

+-------------------------------------------------+
|i1 : R = ZZ/101[a,b,c,d]                         |
|                                                 |
|o1 = R                                           |
|                                                 |
|o1 : PolynomialRing                              |
+-------------------------------------------------+
|i2 : A = koszulComplexDGA(R)                     |
|                                                 |
|o2 = {Ring => R                          }       |
|      Underlying algebra => R[T   ..T   ]        |
|                               1,1   1,4         |
|      Differential => {a, b, c, d}               |
|                                                 |
|o2 : DGAlgebra                                   |
+-------------------------------------------------+
|i3 : S = R/ideal{a^3,a*b*c}                      |
|                                                 |
|o3 = S                                           |
|                                                 |
|o3 : QuotientRing                                |
+-------------------------------------------------+
|i4 : B = A ** S                                  |
|                                                 |
|o4 = {Ring => S                          }       |
|      Underlying algebra => S[T   ..T   ]        |
|                               1,1   1,4         |
|      Differential => {a, b, c, d}               |
|                                                 |
|o4 : DGAlgebra                                   |
+-------------------------------------------------+
|i5 : B === A ** S                                |
|                                                 |
|o5 = true                                        |
+-------------------------------------------------+
|i6 : Bdd = toComplex B                           |
|                                                 |
|      1      4      6      4      1              |
|o6 = S  <-- S  <-- S  <-- S  <-- S               |
|                                                 |
|     0      1      2      3      4               |
|                                                 |
|o6 : Complex                                     |
+-------------------------------------------------+
|i7 : Bdd.dd                                      |
|                                                 |
|          1                   4                  |
|o7 = 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  |                        |
|                                                 |
|o7 : ComplexMap                                  |
+-------------------------------------------------+

Base change along the trivial quotient R / ideal 0_R is structure- preserving:
the result is a well-defined DGAlgebra over a ring isomorphic to R.

+-------------------------------------+
|i8 : R' = ZZ/101[x]                  |
|                                     |
|o8 = R'                              |
|                                     |
|o8 : PolynomialRing                  |
+-------------------------------------+
|i9 : A' = koszulComplexDGA R'        |
|                                     |
|o9 = {Ring => R'                    }|
|      Underlying algebra => R'[T   ] |
|                                1,1  |
|      Differential => {x}            |
|                                     |
|o9 : DGAlgebra                       |
+-------------------------------------+
|i10 : QR' = R' / ideal(0_(R'))       |
|                                     |
|o10 = R'                             |
|                                     |
|o10 : PolynomialRing                 |
+-------------------------------------+
|i11 : isWellDefined(A' ** QR')       |
|                                     |
|o11 = true                           |
+-------------------------------------+

See also
========

  * Base change and tensor with non-DG types
    -- Tensoring DG objects with ordinary rings and modules
  * DGModule ** Ring -- Base change of a DG module
    along a ring map
  * DGAlgebraMap ** Ring -- Base change of a
    DG algebra map along a ring map

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

  * DGAlgebra ** Ring -- Base change of a DG
    algebra to another ring
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1705:0.

DGModule ** Ring -- Base change of a DG module along a ring map
***************************************************************

  * Operator: ** (Macaulay2Doc),
  * Usage:
        MS = M ** S
  * Inputs:
      * M, an instance of the type DGModule, A (free) DG
        module over some DG algebra A.
      * S, a ring (Macaulay2Doc), A ring admitting substitution
        from A.ring.  Typically S = A.ring / I.
  * Outputs:
      * MS, an instance of the type DGModule, A DG module over
        A ** S with the same generator multi-degrees as M and with differential
        obtained by substituting every entry of each differential column into
        the base-changed algebra.

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

This is the base change of M along the ring map A.ring -> S, lifted to the DG
level.  Since A ** S and M ** S are both cached, repeated tensoring with S is
idempotent up to object identity:

+--------------------------------------------+
|i1 : R = ZZ/101[x,y]                        |
|                                            |
|o1 = R                                      |
|                                            |
|o1 : PolynomialRing                         |
+--------------------------------------------+
|i2 : A = koszulComplexDGA R                 |
|                                            |
|o2 = {Ring => R                          }  |
|      Underlying algebra => R[T   ..T   ]   |
|                               1,1   1,2    |
|      Differential => {x, y}                |
|                                            |
|o2 : DGAlgebra                              |
+--------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})            |
|                                            |
|o3 = {Base ring => R                       }|
|      DG algebra => R[T   ..T   ]           |
|                       1,1   1,2            |
|                                       2    |
|      Natural module => (R[T   ..T   ])     |
|                            1,1   1,2       |
|      Generator degrees => {{0, 0}, {1, 0}} |
|      Differentials on gens => {0, 0}       |
|                                            |
|o3 : DGModule                               |
+--------------------------------------------+
|i4 : QR = R / ideal(x^2)                    |
|                                            |
|o4 = QR                                     |
|                                            |
|o4 : QuotientRing                           |
+--------------------------------------------+
|i5 : MS = M ** QR                           |
|                                            |
|o5 = {Base ring => QR                      }|
|      DG algebra => QR[T   ..T   ]          |
|                        1,1   1,2           |
|                                        2   |
|      Natural module => (QR[T   ..T   ])    |
|                             1,1   1,2      |
|      Generator degrees => {{0, 0}, {1, 0}} |
|      Differentials on gens => {0, 0}       |
|                                            |
|o5 : DGModule                               |
+--------------------------------------------+
|i6 : MS === M ** QR                         |
|                                            |
|o6 = true                                   |
+--------------------------------------------+
|i7 : MS.dgAlgebra === A ** QR               |
|                                            |
|o7 = true                                   |
+--------------------------------------------+
|i8 : isWellDefined MS                       |
|                                            |
|o8 = true                                   |
+--------------------------------------------+

When M is the Koszul complex on a sequence and the map A.ring -> S is a
quotient map, M ** S is the Koszul complex of the same sequence computed over
S.

See also
========

  * Base change and tensor with non-DG types
    -- Tensoring DG objects with ordinary rings and modules
  * DGAlgebra ** Ring -- Base change of a DG
    algebra to another ring
  * DGModuleMap ** Ring -- Base change of a DG
    module map along a ring map

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

  * DGModule ** Ring -- Base change of a DG module
    along a ring map
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1821:0.

DGSubmodule ** Ring -- Base change of a DG submodule along a ring map
*********************************************************************

  * Operator: ** (Macaulay2Doc),
  * Usage:
        SubS = Sub ** S
  * Inputs:
      * Sub, an instance of the type DGSubmodule, A DG
        submodule of some ambient DG module M.
      * S, a ring (Macaulay2Doc), A ring admitting substitution
        from the ground ring of Sub.
  * Outputs:
      * SubS, an instance of the type DGSubmodule, The DG
        submodule of M ** S whose inclusion matrix is obtained by substituting
        every entry of the original inclusion into the base-changed ring.

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

The ambient is (Sub.ambient) ** S, so that for any DGQuotientModule built from
Sub the quotient (M/Sub) ** S equals (M ** S) / (Sub ** S)  up to canonical
equality.

+----------------------------------------------------+
|i1 : R = ZZ/101[x,y]                                |
|                                                    |
|o1 = R                                              |
|                                                    |
|o1 : PolynomialRing                                 |
+----------------------------------------------------+
|i2 : A = koszulComplexDGA R                         |
|                                                    |
|o2 = {Ring => R                          }          |
|      Underlying algebra => R[T   ..T   ]           |
|                               1,1   1,2            |
|      Differential => {x, y}                        |
|                                                    |
|o2 : DGAlgebra                                      |
+----------------------------------------------------+
|i3 : Anat = A.natural                               |
|                                                    |
|o3 = Anat                                           |
|                                                    |
|o3 : PolynomialRing, 2 skew commutative variable(s) |
+----------------------------------------------------+
|i4 : M = freeDGModule(A, {0})                       |
|                                                    |
|o4 = {Base ring => R               }                |
|      DG algebra => Anat                            |
|                            1                       |
|      Natural module => Anat                        |
|      Generator degrees => {{0, 0}}                 |
|      Differentials on gens => {0}                  |
|                                                    |
|o4 : DGModule                                       |
+----------------------------------------------------+
|i5 : Sub = dgSubmodule(M, matrix {{x_Anat, y_Anat}})|
|                                                    |
|o5 = DGSubmodule of ambient DGModule                |
|     Degrees  => {{0, 1}, {0, 1}}                   |
|                     2                              |
|     natural  => Anat                               |
|     inclusion => | x y |                           |
|                                                    |
|o5 : DGSubmodule                                    |
+----------------------------------------------------+
|i6 : QR = R / ideal(x^2)                            |
|                                                    |
|o6 = QR                                             |
|                                                    |
|o6 : QuotientRing                                   |
+----------------------------------------------------+
|i7 : SubQ = Sub ** QR                               |
|                                                    |
|o7 = DGSubmodule of ambient DGModule                |
|     Degrees  => {{0, 1}, {0, 1}}                   |
|                                 2                  |
|     natural  => (QR[T   ..T   ])                   |
|                      1,1   1,2                     |
|     inclusion => | x y |                           |
|                                                    |
|o7 : DGSubmodule                                    |
+----------------------------------------------------+
|i8 : isWellDefined SubQ                             |
|                                                    |
|o8 = true                                           |
+----------------------------------------------------+
|i9 : SubQ.ambient === M ** QR                       |
|                                                    |
|o9 = true                                           |
+----------------------------------------------------+

See also
========

  * Base change and tensor with non-DG types
    -- Tensoring DG objects with ordinary rings and modules
  * DGModule ** Ring -- Base change of a DG module
    along a ring map
  * DGQuotientModule ** Ring -- Base
    change of a DG quotient module along a ring map

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

  * DGSubmodule ** Ring -- Base change of a DG
    submodule along a ring map
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1859:0.

DGQuotientModule ** Ring -- Base change of a DG quotient module along a ring map
********************************************************************************

  * Operator: ** (Macaulay2Doc),
  * Usage:
        QS = Q ** S
  * Inputs:
      * Q, an instance of the type DGQuotientModule,
      * S, a ring (Macaulay2Doc),
  * Outputs:
      * QS, an instance of the type DGQuotientModule,
        The quotient (M ** S) / (Sub ** S) where M = Q.ambient and Sub =
        Q.subDGModule.

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

Internally, the submodule is rebuilt directly inside the base-changed ambient
(rather than constructing Sub ** S separately and then quotienting); this is
what ensures the ambient DGModule of the result is the cached M ** S, not a
distinct isomorphic copy.

+---------------------------------------------------+
|i1 : R = ZZ/101[x,y]                               |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : M = freeDGModule(A, {0})                      |
|                                                   |
|o4 = {Base ring => R               }               |
|      DG algebra => Anat                           |
|                            1                      |
|      Natural module => Anat                       |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o4 : DGModule                                      |
+---------------------------------------------------+
|i5 : Sub = dgSubmodule(M, matrix {{x_Anat}})       |
|                                                   |
|o5 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => | x |                            |
|                                                   |
|o5 : DGSubmodule                                   |
+---------------------------------------------------+
|i6 : Q = M / Sub                                   |
|                                                   |
|o6 = DGQuotientModule Q = M / S                    |
|     Q.natural = cokernel | x |                    |
|     Degrees   = {{0, 0}}                          |
|                                                   |
|o6 : DGQuotientModule                              |
+---------------------------------------------------+
|i7 : QR = R / ideal(x^2)                           |
|                                                   |
|o7 = QR                                            |
|                                                   |
|o7 : QuotientRing                                  |
+---------------------------------------------------+
|i8 : QS = Q ** QR                                  |
|                                                   |
|o8 = DGQuotientModule Q = M / S                    |
|     Q.natural = cokernel | x |                    |
|     Degrees   = {{0, 0}}                          |
|                                                   |
|o8 : DGQuotientModule                              |
+---------------------------------------------------+
|i9 : isWellDefined QS                              |
|                                                   |
|o9 = true                                          |
+---------------------------------------------------+
|i10 : QS.ambient === M ** QR                       |
|                                                   |
|o10 = true                                         |
+---------------------------------------------------+

See also
========

  * Base change and tensor with non-DG types
    -- Tensoring DG objects with ordinary rings and modules
  * DGSubmodule ** Ring -- Base change of a DG
    submodule along a ring map
  * DGModule ** Ring -- Base change of a DG module
    along a ring map

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

  * DGQuotientModule ** Ring -- Base
    change of a DG quotient module along a ring map
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1896:0.

DGIdeal ** Ring -- Base change of a DG ideal along a ring map
*************************************************************

  * Operator: ** (Macaulay2Doc),
  * Usage:
        IS = I ** S
  * Inputs:
      * I, an instance of the type DGIdeal, A DG ideal of some
        DG algebra A.
      * S, a ring (Macaulay2Doc),
  * Outputs:
      * IS, an instance of the type DGIdeal, The DG ideal of A
        ** S generated by the images of the original generators of I under
        substitute (Macaulay2Doc).

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

Unlike ** Ideal (which is not defined — see the note in Base change and tensor with non-DG types),
this
operation does land inside the DG world: DGIdeal is always generated by
elements, so substitution along the ring map of base change produces a
well-formed DGIdeal of A ** S.

+---------------------------------------------------+
|i1 : R = ZZ/101[x,y]                               |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : I = dgIdeal(A, {x_Anat, y_Anat})              |
|                                                   |
|o4 = DGIdeal of Anat                               |
|     generators => | y x |                         |
|                                                   |
|o4 : DGIdeal                                       |
+---------------------------------------------------+
|i5 : QR = R / ideal(x^2)                           |
|                                                   |
|o5 = QR                                            |
|                                                   |
|o5 : QuotientRing                                  |
+---------------------------------------------------+
|i6 : IQ = I ** QR                                  |
|                                                   |
|o6 = DGIdeal of QR[T   ..T   ]                     |
|                    1,1   1,2                      |
|     generators => | y x |                         |
|                                                   |
|o6 : DGIdeal                                       |
+---------------------------------------------------+
|i7 : isWellDefined IQ                              |
|                                                   |
|o7 = true                                          |
+---------------------------------------------------+
|i8 : IQ.dgAlgebra === A ** QR                      |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+

Base change preserves the zero and unit DG ideals: the zero ideal stays zero,
and the unit ideal stays the whole algebra.

+----------------------------------------+
|i9 : Z = dgIdeal(A, {})                 |
|                                        |
|o9 = DGIdeal of Anat                    |
|     generators => 0                    |
|                                        |
|o9 : DGIdeal                            |
+----------------------------------------+
|i10 : ZQ = Z ** QR                      |
|                                        |
|o10 = DGIdeal of QR[T   ..T   ]         |
|                     1,1   1,2          |
|      generators => 0                   |
|                                        |
|o10 : DGIdeal                           |
+----------------------------------------+
|i11 : isWellDefined ZQ and isZero ZQ    |
|                                        |
|o11 = true                              |
+----------------------------------------+
|i12 : U = dgIdeal(A, {1_Anat})          |
|                                        |
|o12 = DGIdeal of Anat                   |
|      generators => | 1 |               |
|                                        |
|o12 : DGIdeal                           |
+----------------------------------------+
|i13 : UQ = U ** QR                      |
|                                        |
|o13 = DGIdeal of QR[T   ..T   ]         |
|                     1,1   1,2          |
|      generators => | 1 |               |
|                                        |
|o13 : DGIdeal                           |
+----------------------------------------+
|i14 : isWellDefined UQ and not isZero UQ|
|                                        |
|o14 = true                              |
+----------------------------------------+

Multivariate quotients and multi-generator DG ideals interact as expected.

+----------------------------------------------------+
|i15 : R3 = ZZ/101[x,y,z]                            |
|                                                    |
|o15 = R3                                            |
|                                                    |
|o15 : PolynomialRing                                |
+----------------------------------------------------+
|i16 : A3 = koszulComplexDGA R3                      |
|                                                    |
|o16 = {Ring => R3                          }        |
|       Underlying algebra => R3[T   ..T   ]         |
|                                 1,1   1,3          |
|       Differential => {x, y, z}                    |
|                                                    |
|o16 : DGAlgebra                                     |
+----------------------------------------------------+
|i17 : Anat3 = A3.natural                            |
|                                                    |
|o17 = Anat3                                         |
|                                                    |
|o17 : PolynomialRing, 3 skew commutative variable(s)|
+----------------------------------------------------+
|i18 : I3 = dgIdeal(A3, {x_Anat3, y_Anat3, z_Anat3}) |
|                                                    |
|o18 = DGIdeal of Anat3                              |
|      generators => | z y x |                       |
|                                                    |
|o18 : DGIdeal                                       |
+----------------------------------------------------+
|i19 : QR3 = R3 / ideal(x*y, y*z)                    |
|                                                    |
|o19 = QR3                                           |
|                                                    |
|o19 : QuotientRing                                  |
+----------------------------------------------------+
|i20 : isWellDefined(I3 ** QR3)                      |
|                                                    |
|o20 = true                                          |
+----------------------------------------------------+

See also
========

  * Base change and tensor with non-DG types
    -- Tensoring DG objects with ordinary rings and modules
  * dgIdeal -- Construct a DG ideal from a list, matrix, or
    ideal of generators
  * DGAlgebra ** Ring -- Base change of a DG
    algebra to another ring

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

  * DGIdeal ** Ring -- Base change of a DG ideal
    along a ring map
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1952:0.

DGAlgebraMap ** Ring -- Base change of a DG algebra map along a ring map
************************************************************************

  * Operator: ** (Macaulay2Doc),
  * Usage:
        phiS = phi ** S
  * Inputs:
      * phi, an instance of the type DGAlgebraMap, A DG
        algebra map A -> B.
      * S, a ring (Macaulay2Doc),
  * Outputs:
      * phiS, an instance of the type DGAlgebraMap, A DG
        algebra map A ** S -> B ** S whose underlying RingMap sends each
        generator of A.natural to the image under phi, substituted into (B **
        S).natural.

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

Functorial and compatible with object identity: because A ** S and B ** S are
cached, repeated evaluations of phi ** S land in the same source/target, and
identityDGAlgebraMap(A) ** S equals identityDGAlgebraMap(A ** S).

+-------------------------------------------------------------+
|i1 : R = ZZ/101[x,y]                                         |
|                                                             |
|o1 = R                                                       |
|                                                             |
|o1 : PolynomialRing                                          |
+-------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                  |
|                                                             |
|o2 = {Ring => R                          }                   |
|      Underlying algebra => R[T   ..T   ]                    |
|                               1,1   1,2                     |
|      Differential => {x, y}                                 |
|                                                             |
|o2 : DGAlgebra                                               |
+-------------------------------------------------------------+
|i3 : idA = identityDGAlgebraMap A                            |
|                                                             |
|o3 = map (R[T   ..T   ], R[T   ..T   ], {T   , T   , x, y})  |
|             1,1   1,2      1,1   1,2     1,1   1,2          |
|                                                             |
|o3 : DGAlgebraMap                                            |
+-------------------------------------------------------------+
|i4 : QR = R / ideal(x^2)                                     |
|                                                             |
|o4 = QR                                                      |
|                                                             |
|o4 : QuotientRing                                            |
+-------------------------------------------------------------+
|i5 : idAQ = idA ** QR                                        |
|                                                             |
|o5 = map (QR[T   ..T   ], QR[T   ..T   ], {T   , T   , x, y})|
|              1,1   1,2       1,1   1,2     1,1   1,2        |
|                                                             |
|o5 : DGAlgebraMap                                            |
+-------------------------------------------------------------+
|i6 : isWellDefined idAQ                                      |
|                                                             |
|o6 = true                                                    |
+-------------------------------------------------------------+
|i7 : (idAQ.source) === (A ** QR)                             |
|                                                             |
|o7 = true                                                    |
+-------------------------------------------------------------+
|i8 : (idAQ.target) === (A ** QR)                             |
|                                                             |
|o8 = true                                                    |
+-------------------------------------------------------------+

See also
========

  * Base change and tensor with non-DG types
    -- Tensoring DG objects with ordinary rings and modules
  * DGAlgebra ** Ring -- Base change of a DG
    algebra to another ring
  * identityDGAlgebraMap -- The identity
    DGAlgebraMap on a DG algebra

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

  * DGAlgebraMap ** Ring -- Base change of a
    DG algebra map along a ring map
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1990:0.

DGModuleMap ** Ring -- Base change of a DG module map along a ring map
**********************************************************************

  * Operator: ** (Macaulay2Doc),
  * Usage:
        fS = f ** S
  * Inputs:
      * f, an instance of the type DGModuleMap, A DG module
        map M -> N over a DG algebra A.
      * S, a ring (Macaulay2Doc),
  * Outputs:
      * fS, an instance of the type DGModuleMap, A DG
        module map M ** S -> N ** S (over A ** S) whose underlying matrix is
        obtained entry-wise by substituting each entry of f.natural into the
        base-changed ring.

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

Functorial: identityDGModuleMap(M) ** S equals identityDGModuleMap(M ** S), and
composition is preserved. Cache-identity is what ensures the source and target
of the result are the same cached DG modules as M ** S and N ** S.

+------------------------------------------+
|i1 : R = ZZ/101[x,y]                      |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : M = freeDGModule(A, {0})             |
|                                          |
|o3 = {Base ring => R                    } |
|      DG algebra => R[T   ..T   ]         |
|                       1,1   1,2          |
|                                       1  |
|      Natural module => (R[T   ..T   ])   |
|                            1,1   1,2     |
|      Generator degrees => {{0, 0}}       |
|      Differentials on gens => {0}        |
|                                          |
|o3 : DGModule                             |
+------------------------------------------+
|i4 : idM = identityDGModuleMap M          |
|                                          |
|                               1          |
|o4 = {Source => (R[T   ..T   ]) }         |
|                    1,1   1,2             |
|                               1          |
|      Target => (R[T   ..T   ])           |
|                    1,1   1,2             |
|      Natural => | 1 |                    |
|                                          |
|o4 : DGModuleMap                          |
+------------------------------------------+
|i5 : QR = R / ideal(x^2)                  |
|                                          |
|o5 = QR                                   |
|                                          |
|o5 : QuotientRing                         |
+------------------------------------------+
|i6 : idMQ = idM ** QR                     |
|                                          |
|                                1         |
|o6 = {Source => (QR[T   ..T   ]) }        |
|                     1,1   1,2            |
|                                1         |
|      Target => (QR[T   ..T   ])          |
|                     1,1   1,2            |
|      Natural => | 1 |                    |
|                                          |
|o6 : DGModuleMap                          |
+------------------------------------------+
|i7 : isWellDefined idMQ                   |
|                                          |
|o7 = true                                 |
+------------------------------------------+
|i8 : (idMQ.source) === (M ** QR)          |
|                                          |
|o8 = true                                 |
+------------------------------------------+
|i9 : (idMQ.target) === (M ** QR)          |
|                                          |
|o9 = true                                 |
+------------------------------------------+

Functoriality is literal at the matrix level: the natural matrix of idM ** QR
is the identity matrix on (M ** QR).natural.

+-------------------------------------------+
|i10 : MQ = M ** QR                         |
|                                           |
|o10 = {Base ring => QR                    }|
|       DG algebra => QR[T   ..T   ]        |
|                         1,1   1,2         |
|                                         1 |
|       Natural module => (QR[T   ..T   ])  |
|                              1,1   1,2    |
|       Generator degrees => {{0, 0}}       |
|       Differentials on gens => {0}        |
|                                           |
|o10 : DGModule                             |
+-------------------------------------------+
|i11 : idMQ.natural == id_(MQ.natural)      |
|                                           |
|o11 = true                                 |
+-------------------------------------------+

See also
========

  * Base change and tensor with non-DG types
    -- Tensoring DG objects with ordinary rings and modules
  * DGModule ** Ring -- Base change of a DG module
    along a ring map
  * identityDGModuleMap -- The identity DGModuleMap
    on a DG module

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

  * DGModuleMap ** Ring -- Base change of a DG
    module map along a ring map
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2034:0.

DGModule ** Module -- Exterior tensor product of a DG module with an ordinary free module
*****************************************************************************************

  * Operator: ** (Macaulay2Doc),
  * Usage:
        P = M ** N
        P = N ** M
  * Inputs:
      * M, an instance of the type DGModule, Must be semifree:
        M.natural must be a free A.natural-module.
      * N, a module (Macaulay2Doc), An ordinary module over
        A.ring (or a compatible ring) that is also free.
  * Outputs:
      * P, an instance of the type DGModule, A DG module over
        the same DG algebra A, with rank P.natural = (rank M.natural) * (rank
        N) generators.  The multi-degree of the (i, j)-th natural generator is
        M.Degrees#i + (0, (degrees N)#j) (homological degree from M, internal
        degrees shifted by the internal degree of the j-th generator of N). The
        differential is d_M \otimes id_N.

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

This is the exterior tensor product of DG-modules, where N is viewed as a
complex concentrated in homological degree 0 with zero differential.  The
commuted form N ** M is defined as M ** N.

+--------------------------------------------+
|i1 : R = ZZ/101[x,y]                        |
|                                            |
|o1 = R                                      |
|                                            |
|o1 : PolynomialRing                         |
+--------------------------------------------+
|i2 : A = koszulComplexDGA R                 |
|                                            |
|o2 = {Ring => R                          }  |
|      Underlying algebra => R[T   ..T   ]   |
|                               1,1   1,2    |
|      Differential => {x, y}                |
|                                            |
|o2 : DGAlgebra                              |
+--------------------------------------------+
|i3 : M = freeDGModule(A, {0})               |
|                                            |
|o3 = {Base ring => R                    }   |
|      DG algebra => R[T   ..T   ]           |
|                       1,1   1,2            |
|                                       1    |
|      Natural module => (R[T   ..T   ])     |
|                            1,1   1,2       |
|      Generator degrees => {{0, 0}}         |
|      Differentials on gens => {0}          |
|                                            |
|o3 : DGModule                               |
+--------------------------------------------+
|i4 : N = R^2                                |
|                                            |
|      2                                     |
|o4 = R                                      |
|                                            |
|o4 : R-module, free                         |
+--------------------------------------------+
|i5 : MN = M ** N                            |
|                                            |
|o5 = {Base ring => R                       }|
|      DG algebra => R[T   ..T   ]           |
|                       1,1   1,2            |
|                                       2    |
|      Natural module => (R[T   ..T   ])     |
|                            1,1   1,2       |
|      Generator degrees => {{0, 0}, {0, 0}} |
|      Differentials on gens => {0, 0}       |
|                                            |
|o5 : DGModule                               |
+--------------------------------------------+
|i6 : class MN                               |
|                                            |
|o6 = DGModule                               |
|                                            |
|o6 : Type                                   |
+--------------------------------------------+
|i7 : numgens MN                             |
|                                            |
|o7 = 2                                      |
+--------------------------------------------+
|i8 : isWellDefined MN                       |
|                                            |
|o8 = true                                   |
+--------------------------------------------+

The special case M ** R^1 is canonically isomorphic to M, and M ** R^{d} is a
shift of M by the internal degree d.

Multi-degree M tensors predictably: if M has multiple homological degrees and N
is free of rank r, the result has (rank M.natural) * r natural generators and
is well-defined.

+-----------------------------------------------------------------------------+
|i9 : M2m = freeDGModule(A, {0, 1})                                           |
|                                                                             |
|o9 = {Base ring => R                       }                                 |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       2                                     |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {1, 0}}                                  |
|      Differentials on gens => {0, 0}                                        |
|                                                                             |
|o9 : DGModule                                                                |
+-----------------------------------------------------------------------------+
|i10 : N3 = R^3                                                               |
|                                                                             |
|       3                                                                     |
|o10 = R                                                                      |
|                                                                             |
|o10 : R-module, free                                                         |
+-----------------------------------------------------------------------------+
|i11 : M2N = M2m ** N3                                                        |
|                                                                             |
|o11 = {Base ring => R                                                       }|
|       DG algebra => R[T   ..T   ]                                           |
|                        1,1   1,2                                            |
|                                        6                                    |
|       Natural module => (R[T   ..T   ])                                     |
|                             1,1   1,2                                       |
|       Generator degrees => {{0, 0}, {0, 0}, {0, 0}, {1, 0}, {1, 0}, {1, 0}} |
|       Differentials on gens => {0, 0, 0, 0, 0, 0}                           |
|                                                                             |
|o11 : DGModule                                                               |
+-----------------------------------------------------------------------------+
|i12 : numgens M2N == 2 * 3                                                   |
|                                                                             |
|o12 = true                                                                   |
+-----------------------------------------------------------------------------+
|i13 : isWellDefined M2N                                                      |
|                                                                             |
|o13 = true                                                                   |
+-----------------------------------------------------------------------------+

Edge case: tensoring with the zero module R^0 gives a well-defined zero
DGModule.

+-----------------------------------+
|i14 : MZ = M ** R^0                |
|                                   |
|o14 = {Base ring => R             }|
|       DG algebra => R[T   ..T   ] |
|                        1,1   1,2  |
|       Natural module => 0         |
|       Generator degrees => {}     |
|       Differentials on gens => {} |
|                                   |
|o14 : DGModule                     |
+-----------------------------------+
|i15 : isWellDefined MZ             |
|                                   |
|o15 = true                         |
+-----------------------------------+
|i16 : numgens MZ == 0              |
|                                   |
|o16 = true                         |
+-----------------------------------+

Caveat
======

Both M and N must be free (semifree on the DG side).  For the non-free case,
take an initial free resolution and then tensor.

See also
========

  * Base change and tensor with non-DG types
    -- Tensoring DG objects with ordinary rings and modules
  * DGModule ** Ring -- Base change of a DG module
    along a ring map
  * DGModule ** DGModule -- Exterior tensor
    product of DG modules over DG algebras sharing a ground ring

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

  * DGModule ** Module -- Exterior tensor
    product of a DG module with an ordinary free module
  * "Module ** DGModule"
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2100:0.

DGSubmodule ** Module -- Exterior tensor product of a DG submodule with an ordinary free module
***********************************************************************************************

  * Operator: ** (Macaulay2Doc),
  * Usage:
        SubN = Sub ** N
        SubN = N ** Sub
  * Inputs:
      * Sub, an instance of the type DGSubmodule,
      * N, a module (Macaulay2Doc), A free module over a
        compatible ring.
  * Outputs:
      * SubN, an instance of the type DGSubmodule, The DG
        submodule of (Sub.ambient) ** N whose inclusion acts as inclusion(Sub)
        \otimes id_N on natural generators indexed by (i, j).

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

Equivalently: for each natural generator of N, embed a copy of Sub's inclusion
matrix into the corresponding block of the tensored ambient. The commuted form
N ** Sub is defined as Sub ** N.

+----------------------------------------------------+
|i1 : R = ZZ/101[x,y]                                |
|                                                    |
|o1 = R                                              |
|                                                    |
|o1 : PolynomialRing                                 |
+----------------------------------------------------+
|i2 : A = koszulComplexDGA R                         |
|                                                    |
|o2 = {Ring => R                          }          |
|      Underlying algebra => R[T   ..T   ]           |
|                               1,1   1,2            |
|      Differential => {x, y}                        |
|                                                    |
|o2 : DGAlgebra                                      |
+----------------------------------------------------+
|i3 : Anat = A.natural                               |
|                                                    |
|o3 = Anat                                           |
|                                                    |
|o3 : PolynomialRing, 2 skew commutative variable(s) |
+----------------------------------------------------+
|i4 : M = freeDGModule(A, {0})                       |
|                                                    |
|o4 = {Base ring => R               }                |
|      DG algebra => Anat                            |
|                            1                       |
|      Natural module => Anat                        |
|      Generator degrees => {{0, 0}}                 |
|      Differentials on gens => {0}                  |
|                                                    |
|o4 : DGModule                                       |
+----------------------------------------------------+
|i5 : Sub = dgSubmodule(M, matrix {{x_Anat, y_Anat}})|
|                                                    |
|o5 = DGSubmodule of ambient DGModule                |
|     Degrees  => {{0, 1}, {0, 1}}                   |
|                     2                              |
|     natural  => Anat                               |
|     inclusion => | x y |                           |
|                                                    |
|o5 : DGSubmodule                                    |
+----------------------------------------------------+
|i6 : N = R^2                                        |
|                                                    |
|      2                                             |
|o6 = R                                              |
|                                                    |
|o6 : R-module, free                                 |
+----------------------------------------------------+
|i7 : SubN = Sub ** N                                |
|                                                    |
|o7 = DGSubmodule of ambient DGModule                |
|     Degrees  => {{0, 1}, {0, 1}, {0, 1}, {0, 1}}   |
|                     4                              |
|     natural  => Anat                               |
|     inclusion => | x 0 y 0 |                       |
|                  | 0 x 0 y |                       |
|                                                    |
|o7 : DGSubmodule                                    |
+----------------------------------------------------+
|i8 : isWellDefined SubN                             |
|                                                    |
|o8 = true                                           |
+----------------------------------------------------+
|i9 : SubN.ambient === M ** N                        |
|                                                    |
|o9 = true                                           |
+----------------------------------------------------+

See also
========

  * Base change and tensor with non-DG types
    -- Tensoring DG objects with ordinary rings and modules
  * DGModule ** Module -- Exterior tensor
    product of a DG module with an ordinary free module
  * DGSubmodule ** Ring -- Base change of a DG
    submodule along a ring map

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

  * DGSubmodule ** Module -- Exterior tensor
    product of a DG submodule with an ordinary free module
  * "Module ** DGSubmodule"
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2139:0.

DGQuotientModule ** Module -- Exterior tensor product of a DG quotient module with an ordinary free module
**********************************************************************************************************

  * Operator: ** (Macaulay2Doc),
  * Usage:
        QN = Q ** N
        QN = N ** Q
  * Inputs:
      * Q, an instance of the type DGQuotientModule,
      * N, a module (Macaulay2Doc), A free module over a
        compatible ring.
  * Outputs:
      * QN, an instance of the type DGQuotientModule,
        The DG quotient module (Q.ambient ** N) / (Q.subDGModule ** N), built
        directly inside the tensored ambient so that the ambient of the result
        equals Q.ambient ** N on the nose.

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

The commuted form N ** Q is defined as Q ** N.

+---------------------------------------------------+
|i1 : R = ZZ/101[x,y]                               |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : M = freeDGModule(A, {0})                      |
|                                                   |
|o4 = {Base ring => R               }               |
|      DG algebra => Anat                           |
|                            1                      |
|      Natural module => Anat                       |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o4 : DGModule                                      |
+---------------------------------------------------+
|i5 : Sub = dgSubmodule(M, matrix {{x_Anat}})       |
|                                                   |
|o5 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => | x |                            |
|                                                   |
|o5 : DGSubmodule                                   |
+---------------------------------------------------+
|i6 : Q = M / Sub                                   |
|                                                   |
|o6 = DGQuotientModule Q = M / S                    |
|     Q.natural = cokernel | x |                    |
|     Degrees   = {{0, 0}}                          |
|                                                   |
|o6 : DGQuotientModule                              |
+---------------------------------------------------+
|i7 : N = R^2                                       |
|                                                   |
|      2                                            |
|o7 = R                                             |
|                                                   |
|o7 : R-module, free                                |
+---------------------------------------------------+
|i8 : QN = Q ** N                                   |
|                                                   |
|o8 = DGQuotientModule Q = M / S                    |
|     Q.natural = cokernel | x 0 |                  |
|                          | 0 x |                  |
|     Degrees   = {{0, 0}, {0, 0}}                  |
|                                                   |
|o8 : DGQuotientModule                              |
+---------------------------------------------------+
|i9 : isWellDefined QN                              |
|                                                   |
|o9 = true                                          |
+---------------------------------------------------+
|i10 : QN.ambient === M ** N                        |
|                                                   |
|o10 = true                                         |
+---------------------------------------------------+

See also
========

  * Base change and tensor with non-DG types
    -- Tensoring DG objects with ordinary rings and modules
  * DGModule ** Module -- Exterior tensor
    product of a DG module with an ordinary free module
  * DGQuotientModule ** Ring -- Base
    change of a DG quotient module along a ring map

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

  * DGQuotientModule ** Module, --
    Exterior tensor product of a DG quotient module with an ordinary free
    module
  * "Module ** DGQuotientModule"
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2177:0.

Operations on DG Ideals -- Sum, product, power, intersection, colon, and other ideal-algebra operations on DG ideals
********************************************************************************************************************

A DG ideal of a DG algebra A is a graded ideal of A.natural that is closed
under the differential d of A.  The DGIdeal, type wraps such an
ideal and exposes the standard M2 Ideal (Macaulay2Doc), operations,
each of which preserves d-closure and returns a new DGIdeal.

Constructor: dgIdeal, takes a List, Matrix, or Ideal of elements
of A.natural and iteratively d-saturates the ideal they generate until it is
closed under d.  Warning: if an input element is not a cycle, the d-saturation
enlarges the ideal (possibly to the unit ideal).

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : I = dgIdeal(A, {x_Anat})                      |
|                                                   |
|o4 = DGIdeal of Anat                               |
|     generators => | x |                           |
|                                                   |
|o4 : DGIdeal                                       |
+---------------------------------------------------+
|i5 : J = dgIdeal(A, {y_Anat})                      |
|                                                   |
|o5 = DGIdeal of Anat                               |
|     generators => | y |                           |
|                                                   |
|o5 : DGIdeal                                       |
+---------------------------------------------------+
|i6 : isWellDefined I                               |
|                                                   |
|o6 = true                                          |
+---------------------------------------------------+
|i7 : isDGIdeal(A, I.natural)                       |
|                                                   |
|o7 = true                                          |
+---------------------------------------------------+

Ideal-algebra operations all preserve d-closure by elementary arguments (sum:
d(I+J) \subset dI + dJ \subset I + J; product: by the Leibniz rule;
intersection: direct; power: induction; colon: Leibniz + f J \subset I implies
(df) J \subset I + f(dJ) \subset I). Concretely, they all return well-defined
DGIdeals.

+-----------------------------------+
|i8 : isWellDefined(I + J)          |
|                                   |
|o8 = true                          |
+-----------------------------------+
|i9 : isWellDefined(I * J)          |
|                                   |
|o9 = true                          |
+-----------------------------------+
|i10 : isWellDefined(I^3)           |
|                                   |
|o10 = true                         |
+-----------------------------------+
|i11 : isWellDefined intersect(I, J)|
|                                   |
|o11 = true                         |
+-----------------------------------+
|i12 : isWellDefined(I : J)         |
|                                   |
|o12 = true                         |
+-----------------------------------+

Equality, containment, and reduction mirror the usual behavior on Ideal (Macaulay2Doc).

+--------------------------------+
|i13 : isSubset(I, I + J)        |
|                                |
|o13 = true                      |
+--------------------------------+
|i14 : I != I + J                |
|                                |
|o14 = true                      |
+--------------------------------+
|i15 : (x_Anat^2 % I) == 0       |
|                                |
|o15 = true                      |
+--------------------------------+
|i16 : (y_Anat^2 % I) == y_Anat^2|
|                                |
|o16 = true                      |
+--------------------------------+

Quotient DG algebras: A / I builds the DG algebra whose underlying ring is
A.natural / I.natural, with differential descending from d (well-defined
precisely because I is d-closed).

+----------------------------------+
|i17 : B = A / I                   |
|                                  |
|o17 = {Ring => R                 }|
|                             Anat |
|       Underlying algebra => ---- |
|                               x  |
|       Differential => {0, y}     |
|                                  |
|o17 : DGAlgebra                   |
+----------------------------------+
|i18 : class B                     |
|                                  |
|o18 = DGAlgebra                   |
|                                  |
|o18 : Type                        |
+----------------------------------+
|i19 : isWellDefined B             |
|                                  |
|o19 = true                        |
+----------------------------------+

Compatibility: any operation that takes an Ideal (Macaulay2Doc),
and lives on I.natural can be reached via I.natural, but the wrapped operations
on DGIdeal return DGIdeals (so d-closure is certified on the result by running
through dgIdeal, once more).

See also
========

  * DGIdeal -- The class of d-closed graded ideals of a DG
    algebra
  * dgIdeal -- Construct a DG ideal from a list, matrix, or
    ideal of generators
  * DGIdeal ** Ring -- Base change of a DG ideal
    along a ring map

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2255:0.

DGIdeal -- The class of d-closed graded ideals of a DG algebra
**************************************************************

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

A DGIdeal wraps a graded ideal of A.natural that is closed under the
differential d of A.  It records the ambient DG algebra, the underlying Ideal,
and a chosen set of generators.  Create one via dgIdeal.

The standard ideal-algebra operations (see DGIdeal + DGIdeal,
see DGIdeal * DGIdeal, DGIdeal ^ ZZ,
see intersect(DGIdeal,DGIdeal),
see DGIdeal _colon_ DGIdeal)
all preserve d-closure and return new DGIdeals.  See Operations on DG Ideals,
for a guided tour.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : I = dgIdeal(A, {x_Anat * y_Anat})             |
|                                                   |
|o4 = DGIdeal of Anat                               |
|     generators => | xy |                          |
|                                                   |
|o4 : DGIdeal                                       |
+---------------------------------------------------+
|i5 : class I                                       |
|                                                   |
|o5 = DGIdeal                                       |
|                                                   |
|o5 : Type                                          |
+---------------------------------------------------+
|i6 : ambient I === A                               |
|                                                   |
|o6 = true                                          |
+---------------------------------------------------+
|i7 : ring I === R                                  |
|                                                   |
|o7 = true                                          |
+---------------------------------------------------+
|i8 : numgens I                                     |
|                                                   |
|o8 = 1                                             |
+---------------------------------------------------+

See also
========

  * dgIdeal -- Construct a DG ideal from a list, matrix, or
    ideal of generators
  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * DGAlgebra / DGIdeal -- Quotient DG algebra by a
    DG ideal

Functions and methods returning an object of class DGIdeal:
===========================================================

  * dgIdeal -- Construct a DG ideal from a list, matrix, or
    ideal of generators
  * intersect(DGIdeal,DGIdeal), --
    Intersection of two DG ideals

Methods that use an object of class DGIdeal:
============================================

  * "ambient(DGIdeal)" -- see ambient, -- Accessors for the
    ambient object, inclusion, projection, and killed submodule
  * DGAlgebra / DGIdeal -- Quotient DG algebra by a
    DG ideal
  * DGIdeal * DGIdeal -- Product of two DG ideals
  * DGIdeal * DGModule (missing documentation)
  * DGIdeal * DGSubmodule (missing documentation)
  * DGIdeal ** Ring -- Base change of a DG ideal
    along a ring map
  * DGIdeal + DGIdeal -- Sum of two DG ideals
  * DGIdeal _colon_ DGIdeal -- Ideal quotient
    (colon) of two DG ideals
  * DGIdeal == DGIdeal -- Equality and containment
    of DG ideals
  * "isSubset(DGIdeal,DGIdeal)" -- see DGIdeal == DGIdeal,
    -- Equality and containment of DG ideals
  * DGIdeal ^ ZZ -- Nonnegative integer power of a DG
    ideal
  * ideal(DGIdeal) (missing documentation)
  * isHomogeneous(DGIdeal) -- Predicates on
    a DG ideal
  * "isZero(DGIdeal)" -- see isHomogeneous(DGIdeal),
    -- Predicates on a DG ideal
  * isWellDefined(DGIdeal) -- Verify that a
    DGIdeal has correct structure and is d-closed
  * "generators(DGIdeal)" -- see mingens(DGIdeal),
    -- Basic accessors on a DG ideal
  * mingens(DGIdeal) -- Basic accessors on a DG
    ideal
  * "module(DGIdeal)" -- see mingens(DGIdeal), --
    Basic accessors on a DG ideal
  * "numgens(DGIdeal)" -- see mingens(DGIdeal), --
    Basic accessors on a DG ideal
  * "ring(DGIdeal)" -- see mingens(DGIdeal), --
    Basic accessors on a DG ideal
  * net(DGIdeal) (missing documentation)
  * "minimalPresentation(DGIdeal)" -- see prune(DGIdeal),
    -- Trim a DG ideal down to a minimal generating set
  * prune(DGIdeal) -- Trim a DG ideal down to a
    minimal generating set
  * RingElement % DGIdeal -- Reduce a ring
    element modulo a DG ideal
  * "ZZ % DGIdeal" -- see RingElement % DGIdeal,
    -- Reduce a ring element modulo a DG ideal
  * toComplex(DGIdeal) -- Export a DG ideal to a
    Complex (not yet implemented)

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2287:0.

dgIdeal -- Construct a DG ideal from a list, matrix, or ideal of generators
***************************************************************************

  * Usage:
        I = dgIdeal(A, gs)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * gs, A List of elements of A.natural, a Matrix of such, or an
        Ideal (Macaulay2Doc), of A.natural.
  * Outputs:
      * I, an instance of the type DGIdeal, The smallest
        d-closed ideal of A.natural containing the given generators.
        Constructed by iteratively adjoining derivatives until the ideal
        stabilizes.

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

If the inputs are already cycles, no new generators are introduced and
I.natural is the ordinary ideal they generate.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : xA = sub(x, Anat)                             |
|                                                   |
|o4 = x                                             |
|                                                   |
|o4 : Anat                                          |
+---------------------------------------------------+
|i5 : I = dgIdeal(A, {xA})                          |
|                                                   |
|o5 = DGIdeal of Anat                               |
|     generators => | x |                           |
|                                                   |
|o5 : DGIdeal                                       |
+---------------------------------------------------+
|i6 : numgens I.natural == 1                        |
|                                                   |
|o6 = true                                          |
+---------------------------------------------------+
|i7 : isDGIdeal(A, I.natural)                       |
|                                                   |
|o7 = true                                          |
+---------------------------------------------------+

If a seed element is not a cycle, d-saturation may enlarge the ideal. For the
Koszul complex on {x}, d(T_1) = x, so dgIdeal(A, {T_1})  ends up containing
both T_1 and x.

+-------------------------------------+
|i8 : R' = ZZ/101[x]                  |
|                                     |
|o8 = R'                              |
|                                     |
|o8 : PolynomialRing                  |
+-------------------------------------+
|i9 : A' = koszulComplexDGA R'        |
|                                     |
|o9 = {Ring => R'                    }|
|      Underlying algebra => R'[T   ] |
|                                1,1  |
|      Differential => {x}            |
|                                     |
|o9 : DGAlgebra                       |
+-------------------------------------+
|i10 : T = (A'.natural)_0             |
|                                     |
|o10 = T                              |
|       1,1                           |
|                                     |
|o10 : R'[T   ]                       |
|          1,1                        |
+-------------------------------------+
|i11 : I' = dgIdeal(A', {T})          |
|                                     |
|o11 = DGIdeal of R'[T   ]            |
|                     1,1             |
|      generators => | x T_(1,1) |    |
|                                     |
|o11 : DGIdeal                        |
+-------------------------------------+
|i12 : numgens I'.natural             |
|                                     |
|o12 = 2                              |
+-------------------------------------+
|i13 : isDGIdeal(A', I'.natural)      |
|                                     |
|o13 = true                           |
+-------------------------------------+

A more interesting multi-variable example: over the Koszul algebra of QQ[x, y],
the top-degree exterior product T_1 T_2 has d(T_1 T_2) = -y T_1 + x T_2, and
d-saturation records both the seed and its differential as minimal generators
of the resulting d-closed ideal:

+-----------------------------------------------------------------------------+
|i14 : R2 = QQ[x, y]                                                          |
|                                                                             |
|o14 = R2                                                                     |
|                                                                             |
|o14 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i15 : A2 = koszulComplexDGA R2                                               |
|warning: clearing value of symbol T to allow access to subscripted           |
|       : debug with expression   debug 6944   or with command line           |
|                                                                             |
|o15 = {Ring => R2                          }                                 |
|       Underlying algebra => R2[T   ..T   ]                                  |
|                                 1,1   1,2                                   |
|       Differential => {x, y}                                                |
|                                                                             |
|o15 : DGAlgebra                                                              |
|-----------------------------------------------------------------------------|
|variables based on it                                                        |
|option   --debug 6944                                                        |
+-----------------------------------------------------------------------------+
|i16 : T1 = (A2.natural)_0                                                    |
|                                                                             |
|o16 = T                                                                      |
|       1,1                                                                   |
|                                                                             |
|o16 : R2[T   ..T   ]                                                         |
|          1,1   1,2                                                          |
+-----------------------------------------------------------------------------+
|i17 : T2 = (A2.natural)_1                                                    |
|                                                                             |
|o17 = T                                                                      |
|       1,2                                                                   |
|                                                                             |
|o17 : R2[T   ..T   ]                                                         |
|          1,1   1,2                                                          |
+-----------------------------------------------------------------------------+
|i18 : polyDifferential(A2, T1 * T2)                                          |
|                                                                             |
|o18 = - y*T    + x*T                                                         |
|           1,1      1,2                                                      |
|                                                                             |
|o18 : R2[T   ..T   ]                                                         |
|          1,1   1,2                                                          |
+-----------------------------------------------------------------------------+
|i19 : J = dgIdeal(A2, {T1 * T2})                                             |
|                                                                             |
|o19 = DGIdeal of R2[T   ..T   ]                                              |
|                     1,1   1,2                                               |
|      generators => | yT_(1,1)-xT_(1,2) T_(1,1)T_(1,2) |                     |
|                                                                             |
|o19 : DGIdeal                                                                |
+-----------------------------------------------------------------------------+
|i20 : mingens J.natural                                                      |
|                                                                             |
|o20 = | yT_(1,1)-xT_(1,2) T_(1,1)T_(1,2) |                                   |
|                                                                             |
|                             1                     2                         |
|o20 : Matrix (R2[T   ..T   ])  <-- (R2[T   ..T   ])                          |
|                  1,1   1,2             1,1   1,2                            |
+-----------------------------------------------------------------------------+

An empty seed or a list of zero seeds yields the zero DG ideal.

+---------------------------------------+
|i21 : Z = dgIdeal(A, {})               |
|                                       |
|o21 = DGIdeal of Anat                  |
|      generators => 0                  |
|                                       |
|o21 : DGIdeal                          |
+---------------------------------------+
|i22 : isWellDefined Z                  |
|                                       |
|o22 = true                             |
+---------------------------------------+
|i23 : isZero Z                         |
|                                       |
|o23 = true                             |
+---------------------------------------+
|i24 : Z' = dgIdeal(A, {0_Anat, 0_Anat})|
|                                       |
|o24 = DGIdeal of Anat                  |
|      generators => 0                  |
|                                       |
|o24 : DGIdeal                          |
+---------------------------------------+
|i25 : isZero Z'                        |
|                                       |
|o25 = true                             |
+---------------------------------------+

A seed containing 1 gives the unit DG ideal.

+--------------------------------------+
|i26 : U = dgIdeal(A, {1_Anat, x_Anat})|
|                                      |
|o26 = DGIdeal of Anat                 |
|      generators => | 1 |             |
|                                      |
|o26 : DGIdeal                         |
+--------------------------------------+
|i27 : U.natural == ideal 1_Anat       |
|                                      |
|o27 = true                            |
+--------------------------------------+

See also
========

  * DGIdeal -- The class of d-closed graded ideals of a DG
    algebra
  * isDGIdeal -- Test whether an ideal of A.natural is closed
    under the differential of A
  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals

Ways to use dgIdeal:
====================

  * "dgIdeal(DGAlgebra,Ideal)"
  * "dgIdeal(DGAlgebra,List)"
  * "dgIdeal(DGAlgebra,Matrix)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2364:0.

isDGIdeal -- Test whether an ideal of A.natural is closed under the differential of A
*************************************************************************************

  * Usage:
        b = isDGIdeal(A, I)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * I, an ideal (Macaulay2Doc), An ideal of A.natural.
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), True iff every
        minimal generator g of I satisfies polyDifferential(A, g) % I == 0.

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

Unlike dgIdeal, (which d-saturates), isDGIdeal simply checks
d-closure without modifying the input.  Use it to validate that an
externally-produced Ideal is already a DG ideal.

+------------------------------------------------------------+
|i1 : R = ZZ/101[x, y]                                       |
|                                                            |
|o1 = R                                                      |
|                                                            |
|o1 : PolynomialRing                                         |
+------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                 |
|                                                            |
|o2 = {Ring => R                          }                  |
|      Underlying algebra => R[T   ..T   ]                   |
|                               1,1   1,2                    |
|      Differential => {x, y}                                |
|                                                            |
|o2 : DGAlgebra                                              |
+------------------------------------------------------------+
|i3 : Anat = A.natural                                       |
|                                                            |
|o3 = Anat                                                   |
|                                                            |
|o3 : PolynomialRing, 2 skew commutative variable(s)         |
+------------------------------------------------------------+
|i4 : isDGIdeal(A, ideal(x_Anat, y_Anat))                    |
|                                                            |
|o4 = true                                                   |
+------------------------------------------------------------+
|i5 : T = Anat_0   -- first Koszul variable T_{1,1}; d(T) = x|
|                                                            |
|o5 = T                                                      |
|      1,1                                                   |
|                                                            |
|o5 : Anat                                                   |
+------------------------------------------------------------+
|i6 : isDGIdeal(A, ideal(T))                                 |
|                                                            |
|o6 = false                                                  |
+------------------------------------------------------------+

The second test returns false: the ideal (T) is not d-closed because d(T) = x
is not in it.  Passing the same seed to dgIdeal, produces the
d-closure.

+--------------------------------+
|i7 : J = dgIdeal(A, {T})        |
|                                |
|o7 = DGIdeal of Anat            |
|     generators => | x T_(1,1) ||
|                                |
|o7 : DGIdeal                    |
+--------------------------------+
|i8 : isDGIdeal(A, J.natural)    |
|                                |
|o8 = true                       |
+--------------------------------+

See also
========

  * dgIdeal -- Construct a DG ideal from a list, matrix, or
    ideal of generators
  * DGIdeal -- The class of d-closed graded ideals of a DG
    algebra

Ways to use isDGIdeal:
======================

  * "isDGIdeal(DGAlgebra,Ideal)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2404:0.

isWellDefined(DGIdeal) -- Verify that a DGIdeal has correct structure and is d-closed
*************************************************************************************

  * Function: isWellDefined (Macaulay2Doc),
  * Usage:
        b = isWellDefined I
  * Inputs:
      * I, an instance of the type DGIdeal,
  * Outputs:
      * b, a Boolean value (Macaulay2Doc),

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

Performs (1) a key-shape check — the expected fields (dgAlgebra, ring, natural,
generators, cache) are present and have the correct types — and (2) the
semantic d-closure check via isDGIdeal.  Set debugLevel > 0
to see a diagnostic message on failure.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : I = dgIdeal(A, {x_Anat, y_Anat})              |
|                                                   |
|o4 = DGIdeal of Anat                               |
|     generators => | y x |                         |
|                                                   |
|o4 : DGIdeal                                       |
+---------------------------------------------------+
|i5 : isWellDefined I                               |
|                                                   |
|o5 = true                                          |
+---------------------------------------------------+

See also
========

  * dgIdeal -- Construct a DG ideal from a list, matrix, or
    ideal of generators
  * isDGIdeal -- Test whether an ideal of A.natural is closed
    under the differential of A
  * DGIdeal -- The class of d-closed graded ideals of a DG
    algebra

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

  * isWellDefined(DGIdeal) -- Verify that a
    DGIdeal has correct structure and is d-closed
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2433:0.

DGIdeal + DGIdeal -- Sum of two DG ideals
*****************************************

  * Operator: + (Macaulay2Doc),
  * Usage:
        K = I + J
  * Inputs:
      * I, an instance of the type DGIdeal,
      * J, an instance of the type DGIdeal, With I.dgAlgebra
        === J.dgAlgebra.
  * Outputs:
      * K, an instance of the type DGIdeal, The DGIdeal with
        K.natural = I.natural + J.natural.

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

Preserves d-closure because d(I + J) \subset dI + dJ \subset I + J.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : I = dgIdeal(A, {x_Anat})                      |
|                                                   |
|o4 = DGIdeal of Anat                               |
|     generators => | x |                           |
|                                                   |
|o4 : DGIdeal                                       |
+---------------------------------------------------+
|i5 : J = dgIdeal(A, {y_Anat})                      |
|                                                   |
|o5 = DGIdeal of Anat                               |
|     generators => | y |                           |
|                                                   |
|o5 : DGIdeal                                       |
+---------------------------------------------------+
|i6 : K = I + J                                     |
|                                                   |
|o6 = DGIdeal of Anat                               |
|     generators => | y x |                         |
|                                                   |
|o6 : DGIdeal                                       |
+---------------------------------------------------+
|i7 : isWellDefined K                               |
|                                                   |
|o7 = true                                          |
+---------------------------------------------------+
|i8 : (I + J) == (J + I)                            |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+

The zero DGIdeal is a two-sided identity for +.

+-----------------------+
|i9 : Z = dgIdeal(A, {})|
|                       |
|o9 = DGIdeal of Anat   |
|     generators => 0   |
|                       |
|o9 : DGIdeal           |
+-----------------------+
|i10 : (Z + I) == I     |
|                       |
|o10 = true             |
+-----------------------+

See also
========

  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * DGIdeal * DGIdeal -- Product of two DG ideals
  * intersect(DGIdeal,DGIdeal), --
    Intersection of two DG ideals

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

  * DGIdeal + DGIdeal -- Sum of two DG ideals
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2470:0.

DGIdeal * DGIdeal -- Product of two DG ideals
*********************************************

  * Operator: * (Macaulay2Doc),
  * Usage:
        K = I * J
  * Inputs:
      * I, an instance of the type DGIdeal,
      * J, an instance of the type DGIdeal, With I.dgAlgebra
        === J.dgAlgebra.
  * Outputs:
      * K, an instance of the type DGIdeal, The DGIdeal with
        K.natural = I.natural * J.natural.

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

Preserves d-closure by the Leibniz rule: d(ab) = d(a) b \pm a d(b) shows d(IJ)
\subset (dI) J + I (dJ) \subset IJ.  When the ambient ring is commutative,
multiplication is commutative.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : I = dgIdeal(A, {x_Anat})                      |
|                                                   |
|o4 = DGIdeal of Anat                               |
|     generators => | x |                           |
|                                                   |
|o4 : DGIdeal                                       |
+---------------------------------------------------+
|i5 : J = dgIdeal(A, {y_Anat})                      |
|                                                   |
|o5 = DGIdeal of Anat                               |
|     generators => | y |                           |
|                                                   |
|o5 : DGIdeal                                       |
+---------------------------------------------------+
|i6 : K = I * J                                     |
|                                                   |
|o6 = DGIdeal of Anat                               |
|     generators => | xy |                          |
|                                                   |
|o6 : DGIdeal                                       |
+---------------------------------------------------+
|i7 : isWellDefined K                               |
|                                                   |
|o7 = true                                          |
+---------------------------------------------------+
|i8 : (I * J) == (J * I)                            |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+

The unit DGIdeal is a two-sided identity for * (as ideals).

+-----------------------------+
|i9 : U = dgIdeal(A, {1_Anat})|
|                             |
|o9 = DGIdeal of Anat         |
|     generators => | 1 |     |
|                             |
|o9 : DGIdeal                 |
+-----------------------------+
|i10 : (U * I) == I           |
|                             |
|o10 = true                   |
+-----------------------------+

See also
========

  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * DGIdeal + DGIdeal -- Sum of two DG ideals
  * DGIdeal ^ ZZ -- Nonnegative integer power of a DG
    ideal

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

  * DGIdeal * DGIdeal -- Product of two DG ideals
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2509:0.

DGIdeal ^ ZZ -- Nonnegative integer power of a DG ideal
*******************************************************

  * Operator: ^ (Macaulay2Doc),
  * Usage:
        K = I^n
  * Inputs:
      * I, an instance of the type DGIdeal,
      * n, an integer (Macaulay2Doc), A nonnegative integer.
  * Outputs:
      * K, an instance of the type DGIdeal, I^0 is the unit
        DGIdeal (1); I^n for n >= 1 is the n-fold product I * I * ... * I.

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

Distributes with multiplication: I^2 * I == I^3.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : I = dgIdeal(A, {x_Anat, y_Anat})              |
|                                                   |
|o4 = DGIdeal of Anat                               |
|     generators => | y x |                         |
|                                                   |
|o4 : DGIdeal                                       |
+---------------------------------------------------+
|i5 : isWellDefined(I^2)                            |
|                                                   |
|o5 = true                                          |
+---------------------------------------------------+
|i6 : isWellDefined(I^3)                            |
|                                                   |
|o6 = true                                          |
+---------------------------------------------------+
|i7 : (I^2 * I) == I^3                              |
|                                                   |
|o7 = true                                          |
+---------------------------------------------------+

I^0 always returns the unit DGIdeal (1).  Taking powers of the zero DG ideal is
well-defined at every exponent.

+-----------------------------------------------+
|i8 : I^0                                       |
|                                               |
|o8 = DGIdeal of Anat                           |
|     generators => | 1 |                       |
|                                               |
|o8 : DGIdeal                                   |
+-----------------------------------------------+
|i9 : Z = dgIdeal(A, {})                        |
|                                               |
|o9 = DGIdeal of Anat                           |
|     generators => 0                           |
|                                               |
|o9 : DGIdeal                                   |
+-----------------------------------------------+
|i10 : isWellDefined(Z^0) and isWellDefined(Z^5)|
|                                               |
|o10 = true                                     |
+-----------------------------------------------+

Caveat
======

Negative exponents are rejected with an error.

See also
========

  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * DGIdeal * DGIdeal -- Product of two DG ideals

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

  * DGIdeal ^ ZZ -- Nonnegative integer power of a DG
    ideal
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2549:0.

intersect(DGIdeal,DGIdeal) -- Intersection of two DG ideals
***********************************************************

  * Function: intersect (Macaulay2Doc),
  * Usage:
        K = intersect(I, J)
  * Inputs:
      * I, an instance of the type DGIdeal,
      * J, an instance of the type DGIdeal, With I.dgAlgebra
        === J.dgAlgebra.
  * Outputs:
      * K, an instance of the type DGIdeal, The DGIdeal with
        K.natural = intersect(I.natural, J.natural).

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

Intersections preserve d-closure directly: if g lies in both I and J, then d(g)
lies in both (by d-closure of each), hence in their intersection.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : I = dgIdeal(A, {x_Anat})                      |
|                                                   |
|o4 = DGIdeal of Anat                               |
|     generators => | x |                           |
|                                                   |
|o4 : DGIdeal                                       |
+---------------------------------------------------+
|i5 : J = dgIdeal(A, {y_Anat})                      |
|                                                   |
|o5 = DGIdeal of Anat                               |
|     generators => | y |                           |
|                                                   |
|o5 : DGIdeal                                       |
+---------------------------------------------------+
|i6 : K = intersect(I, J)                           |
|                                                   |
|o6 = DGIdeal of Anat                               |
|     generators => | xy |                          |
|                                                   |
|o6 : DGIdeal                                       |
+---------------------------------------------------+
|i7 : isWellDefined K                               |
|                                                   |
|o7 = true                                          |
+---------------------------------------------------+

Intersecting with the zero DGIdeal yields the zero DGIdeal.

+-----------------------------+
|i8 : Z = dgIdeal(A, {})      |
|                             |
|o8 = DGIdeal of Anat         |
|     generators => 0         |
|                             |
|o8 : DGIdeal                 |
+-----------------------------+
|i9 : ZI = intersect(Z, I)    |
|                             |
|o9 = DGIdeal of Anat         |
|     generators => 0         |
|                             |
|o9 : DGIdeal                 |
+-----------------------------+
|i10 : isWellDefined ZI       |
|                             |
|o10 = true                   |
+-----------------------------+
|i11 : numgens ZI.natural == 0|
|                             |
|o11 = true                   |
+-----------------------------+

See also
========

  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * DGIdeal + DGIdeal -- Sum of two DG ideals
  * DGIdeal * DGIdeal -- Product of two DG ideals

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

  * intersect(DGIdeal,DGIdeal), --
    Intersection of two DG ideals
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2588:0.

DGIdeal : DGIdeal -- Ideal quotient (colon) of two DG ideals
************************************************************

  * Operator: _colon_ (Macaulay2Doc),
  * Usage:
        K = I : J
  * Inputs:
      * I, an instance of the type DGIdeal,
      * J, an instance of the type DGIdeal, With I.dgAlgebra
        === J.dgAlgebra.
  * Outputs:
      * K, an instance of the type DGIdeal, The DGIdeal with
        K.natural = I.natural : J.natural — i.e. { f \in A.natural | f J
        \subset I }.

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

Preserves d-closure: if f J \subset I then by Leibniz d(f) J = d(fJ) - f d(J)
\subset dI + f J \subset I + I = I, so d(f) \in I : J.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : I = dgIdeal(A, {x_Anat * y_Anat})             |
|                                                   |
|o4 = DGIdeal of Anat                               |
|     generators => | xy |                          |
|                                                   |
|o4 : DGIdeal                                       |
+---------------------------------------------------+
|i5 : J = dgIdeal(A, {y_Anat})                      |
|                                                   |
|o5 = DGIdeal of Anat                               |
|     generators => | y |                           |
|                                                   |
|o5 : DGIdeal                                       |
+---------------------------------------------------+
|i6 : K = I : J                                     |
|                                                   |
|o6 = DGIdeal of Anat                               |
|     generators => | x |                           |
|                                                   |
|o6 : DGIdeal                                       |
+---------------------------------------------------+
|i7 : isWellDefined K                               |
|                                                   |
|o7 = true                                          |
+---------------------------------------------------+

See also
========

  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * DGIdeal * DGIdeal -- Product of two DG ideals

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

  * DGIdeal _colon_ DGIdeal -- Ideal quotient
    (colon) of two DG ideals
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2621:0.

DGIdeal == DGIdeal -- Equality and containment of DG ideals
***********************************************************

  * Operator: == (Macaulay2Doc),
  * Usage:
        b = I == J
        b = isSubset(I, J)
  * Inputs:
      * I, an instance of the type DGIdeal,
      * J, an instance of the type DGIdeal,
  * Outputs:
      * b, a Boolean value (Macaulay2Doc),

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

Both compare DGIdeals via their underlying Ideals I.natural and J.natural.
Equality additionally requires the DG algebras to be the same object (===  —
object identity, not just isomorphism).  Containment also asserts that I and J
share an ambient DG algebra.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : I = dgIdeal(A, {x_Anat})                      |
|                                                   |
|o4 = DGIdeal of Anat                               |
|     generators => | x |                           |
|                                                   |
|o4 : DGIdeal                                       |
+---------------------------------------------------+
|i5 : J = dgIdeal(A, {x_Anat, y_Anat})              |
|                                                   |
|o5 = DGIdeal of Anat                               |
|     generators => | y x |                         |
|                                                   |
|o5 : DGIdeal                                       |
+---------------------------------------------------+
|i6 : isSubset(I, J)                                |
|                                                   |
|o6 = true                                          |
+---------------------------------------------------+
|i7 : I != J                                        |
|                                                   |
|o7 = true                                          |
+---------------------------------------------------+
|i8 : I == I                                        |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+

See also
========

  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * DGIdeal + DGIdeal -- Sum of two DG ideals

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

  * DGIdeal == DGIdeal -- Equality and containment
    of DG ideals
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2656:0.

RingElement % DGIdeal -- Reduce a ring element modulo a DG ideal
****************************************************************

  * Operator: % (Macaulay2Doc),
  * Usage:
        r = f % I
  * Inputs:
      * f, a ring element (Macaulay2Doc), A RingElement of
        I.dgAlgebra.natural, or an integer (coerced into I.dgAlgebra.natural
        before reduction).
      * I, an instance of the type DGIdeal,
  * Outputs:
      * r, a ring element (Macaulay2Doc), The normal form of
        f modulo I.natural.

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

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : I = dgIdeal(A, {x_Anat})                      |
|                                                   |
|o4 = DGIdeal of Anat                               |
|     generators => | x |                           |
|                                                   |
|o4 : DGIdeal                                       |
+---------------------------------------------------+
|i5 : (x_Anat^2 % I) == 0                           |
|                                                   |
|o5 = true                                          |
+---------------------------------------------------+
|i6 : (y_Anat^2 % I) == y_Anat^2                    |
|                                                   |
|o6 = true                                          |
+---------------------------------------------------+

See also
========

  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * DGIdeal == DGIdeal -- Equality and containment
    of DG ideals

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

  * RingElement % DGIdeal -- Reduce a ring
    element modulo a DG ideal
  * "ZZ % DGIdeal"
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2685:0.

mingens(DGIdeal) -- Basic accessors on a DG ideal
*************************************************

  * Function: mingens (Macaulay2Doc),

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

Thin wrappers around the corresponding Ideal (Macaulay2Doc),
operations on I.natural, with the exception of ambient I, which returns the
ambient DGAlgebra, (not its underlying ring).

mingens I returns the minimal-generator matrix of I.natural.  Note that the
d-saturation in dgIdeal, may have produced redundant generators;
mingens I re-extracts a minimal set.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : I = dgIdeal(A, {x_Anat, x_Anat * y_Anat})     |
|                                                   |
|o4 = DGIdeal of Anat                               |
|     generators => | x |                           |
|                                                   |
|o4 : DGIdeal                                       |
+---------------------------------------------------+
|i5 : mingens I                                     |
|                                                   |
|o5 = | x |                                         |
|                                                   |
|                1         1                        |
|o5 : Matrix Anat  <-- Anat                         |
+---------------------------------------------------+
|i6 : numgens I                                     |
|                                                   |
|o6 = 1                                             |
+---------------------------------------------------+

numgens I equals numgens I.natural — the number of (stored, possibly redundant)
generators of the underlying ideal.

+-----------------------------------+
|i7 : numgens I == numgens I.natural|
|                                   |
|o7 = true                          |
+-----------------------------------+

module I returns the underlying Module-view of the ideal, and ring I, ambient
I, generators I expose the ground ring, the ambient DG algebra, and the chosen
generator matrix, respectively.

+-------------------------------------+
|i8 : ring I === R                    |
|                                     |
|o8 = true                            |
+-------------------------------------+
|i9 : ambient I === A                 |
|                                     |
|o9 = true                            |
+-------------------------------------+
|i10 : module I                       |
|                                     |
|o10 = image | x |                    |
|                                     |
|                                    1|
|o10 : Anat-module, submodule of Anat |
+-------------------------------------+

See also
========

  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * dgIdeal -- Construct a DG ideal from a list, matrix, or
    ideal of generators
  * prune(DGIdeal) -- Trim a DG ideal down to a
    minimal generating set

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

  * mingens(DGIdeal) -- Basic accessors on a DG
    ideal
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2730:0.

prune(DGIdeal) -- Trim a DG ideal down to a minimal generating set
******************************************************************

  * Function: prune (Macaulay2Doc),
  * Usage:
        J = prune I
        J = minimalPresentation I
  * Inputs:
      * I, an instance of the type DGIdeal,
  * Optional inputs (Macaulay2Doc),:
      * Exclude (Macaulay2Doc), => ...,
        default value {},
  * Outputs:
      * J, an instance of the type DGIdeal, A DGIdeal with
        J.natural == I.natural (as ideals) but with a possibly smaller
        generator list obtained by trim (Macaulay2Doc).

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

prune computes trim I.natural and wraps the result. It caches a pruningMap in
J.cache giving the canonical comparison map J -> I; since DGIdeals have the
same ambient DG algebra before and after pruning, this is recorded as the
identity DGAlgebraMap on I.dgAlgebra.

+--------------------------------------------------------+
|i1 : R = ZZ/101[x, y]                                   |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                          }              |
|      Underlying algebra => R[T   ..T   ]               |
|                               1,1   1,2                |
|      Differential => {x, y}                            |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : Anat = A.natural                                   |
|                                                        |
|o3 = Anat                                               |
|                                                        |
|o3 : PolynomialRing, 2 skew commutative variable(s)     |
+--------------------------------------------------------+
|i4 : I = dgIdeal(A, {x_Anat, x_Anat * y_Anat, x_Anat^2})|
|                                                        |
|o4 = DGIdeal of Anat                                    |
|     generators => | x |                                |
|                                                        |
|o4 : DGIdeal                                            |
+--------------------------------------------------------+
|i5 : J = prune I                                        |
|                                                        |
|o5 = DGIdeal of Anat                                    |
|     generators => | x |                                |
|                                                        |
|o5 : DGIdeal                                            |
+--------------------------------------------------------+
|i6 : isWellDefined J                                    |
|                                                        |
|o6 = true                                               |
+--------------------------------------------------------+
|i7 : J.natural == I.natural                             |
|                                                        |
|o7 = true                                               |
+--------------------------------------------------------+

Idempotent: pruning an already-minimal DGIdeal is a no-op at the ideal level
(the stored generator list already agrees with mingens).  Repeated pruning is
safe.

+--------------------------------------+
|i8 : isWellDefined prune prune prune J|
|                                      |
|o8 = true                             |
+--------------------------------------+

minimalPresentation is a synonym for prune on DGIdeals.

See also
========

  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * mingens(DGIdeal) -- Basic accessors on a DG
    ideal
  * dgIdeal -- Construct a DG ideal from a list, matrix, or
    ideal of generators

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

  * prune(DGIdeal) -- Trim a DG ideal down to a
    minimal generating set
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2775:0.

DGAlgebra / DGIdeal -- Quotient DG algebra by a DG ideal
********************************************************

  * Operator: / (Macaulay2Doc),
  * Usage:
        B = A / I
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * I, an instance of the type DGIdeal, A DG ideal of A.
        Must satisfy I.dgAlgebra === A.
  * Outputs:
      * B, an instance of the type DGAlgebra, A DG algebra
        whose underlying ring is A.natural / I.natural and whose differential
        is the (well-defined) descent of d_A.

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

The descent is well-defined precisely because I is d-closed: for any lift g' of
a class g in B, the difference g - g' lies in I, so d_A(g) - d_A(g') \in d_A(I)
\subset I and the image [d_A(g)] \in B is independent of the chosen lift.

+---------------------------------------------------+
|i1 : R = ZZ/101[x]                                 |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                    }               |
|      Underlying algebra => R[T   ]                |
|                               1,1                 |
|      Differential => {x}                          |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 1 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : T = Anat_0                                    |
|                                                   |
|o4 = T                                             |
|      1,1                                          |
|                                                   |
|o4 : Anat                                          |
+---------------------------------------------------+
|i5 : I = dgIdeal(A, {T})                           |
|                                                   |
|o5 = DGIdeal of Anat                               |
|     generators => | x T_(1,1) |                   |
|                                                   |
|o5 : DGIdeal                                       |
+---------------------------------------------------+
|i6 : B = A / I                                     |
|                                                   |
|o6 = {Ring => R                      }             |
|                               Anat                |
|      Underlying algebra => ---------              |
|                            (x, T   )              |
|                                 1,1               |
|      Differential => {0}                          |
|                                                   |
|o6 : DGAlgebra                                     |
+---------------------------------------------------+
|i7 : isWellDefined B                               |
|                                                   |
|o7 = true                                          |
+---------------------------------------------------+
|i8 : B.natural                                     |
|                                                   |
|        Anat                                       |
|o8 = ---------                                     |
|     (x, T   )                                     |
|          1,1                                      |
|                                                   |
|o8 : QuotientRing                                  |
+---------------------------------------------------+

See also
========

  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * DGIdeal -- The class of d-closed graded ideals of a DG
    algebra
  * dgIdeal -- Construct a DG ideal from a list, matrix, or
    ideal of generators

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

  * DGAlgebra / DGIdeal -- Quotient DG algebra by a
    DG ideal
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2811:0.

isHomogeneous(DGIdeal) -- Predicates on a DG ideal
**************************************************

  * Function: isHomogeneous (Macaulay2Doc),

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

isHomogeneous I returns isHomogeneous I.natural — i.e. tests whether the
underlying ideal is homogeneous with respect to the grading of A.natural.

isZero I returns true iff I.natural is the zero ideal (equivalently, numgens
I.natural == 0).

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : I = dgIdeal(A, {x_Anat, y_Anat})              |
|                                                   |
|o4 = DGIdeal of Anat                               |
|     generators => | y x |                         |
|                                                   |
|o4 : DGIdeal                                       |
+---------------------------------------------------+
|i5 : isHomogeneous I                               |
|                                                   |
|o5 = true                                          |
+---------------------------------------------------+
|i6 : isZero I                                      |
|                                                   |
|o6 = false                                         |
+---------------------------------------------------+
|i7 : Z = dgIdeal(A, {})                            |
|                                                   |
|o7 = DGIdeal of Anat                               |
|     generators => 0                               |
|                                                   |
|o7 : DGIdeal                                       |
+---------------------------------------------------+
|i8 : isZero Z                                      |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+

See also
========

  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * DGIdeal -- The class of d-closed graded ideals of a DG
    algebra

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

  * isHomogeneous(DGIdeal) -- Predicates on
    a DG ideal
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2839:0.

Building DG modules, submodules, and quotients -- The DGModule / DGSubmodule / DGQuotientModule hierarchy and its constructors
******************************************************************************************************************************

The package provides three related types of DG-module-like objects over a fixed
DGAlgebra, A:

DGModule, — a free graded A.natural-module equipped with a
differential that satisfies the Leibniz rule against A. Built via
freeDGModule, with differentials set by setDiff.

See DGSubmodule, — a subobject of a DGModule M, represented by a
matrix of generators whose column span is closed under the differential of M.
Built via dgSubmodule, which d-saturates the seed
generators automatically.

See DGQuotientModule, — the cokernel M / S of the inclusion
S → M, with the induced differential.  Built via dgQuotientModule,
or the shorthand M / S.

Every object in this hierarchy carries an underlying graded A.natural-module
accessible via M.natural, a list of multi-degrees M.Degrees, and a list of
differentials M.diff (one per natural generator for DGModule and DGSubmodule;
per quotient-presentation generator for DGQuotientModule).  Structural
correctness can be checked with isWellDefined (Macaulay2Doc).

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                   |
|                                                   |
|o3 = {Base ring => R                       }       |
|      DG algebra => R[T   ..T   ]                  |
|                       1,1   1,2                   |
|                                       2           |
|      Natural module => (R[T   ..T   ])            |
|                            1,1   1,2              |
|      Generator degrees => {{0, 0}, {1, 0}}        |
|      Differentials on gens => {0, 0}              |
|                                                   |
|o3 : DGModule                                      |
+---------------------------------------------------+
|i4 : isWellDefined M                               |
|                                                   |
|o4 = true                                          |
+---------------------------------------------------+
|i5 : Anat = A.natural                              |
|                                                   |
|o5 = Anat                                          |
|                                                   |
|o5 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i6 : S = dgSubmodule(M, (id_(M.natural))_{0})      |
|                                                   |
|o6 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 0}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => {0, 0} | 1 |                     |
|                  {1, 0} | 0 |                     |
|                                                   |
|o6 : DGSubmodule                                   |
+---------------------------------------------------+
|i7 : isWellDefined S                               |
|                                                   |
|o7 = true                                          |
+---------------------------------------------------+
|i8 : Q = M / S                                     |
|                                                   |
|o8 = DGQuotientModule Q = M / S                    |
|     Q.natural = cokernel {0, 0} | 1 |             |
|                          {1, 0} | 0 |             |
|     Degrees   = {{0, 0}, {1, 0}}                  |
|                                                   |
|o8 : DGQuotientModule                              |
+---------------------------------------------------+
|i9 : isWellDefined Q                               |
|                                                   |
|o9 = true                                          |
+---------------------------------------------------+

See also
========

  * Module-like operations on DG modules
    -- Basic queries (generators, rank, degrees, homogeneity) extended
    to DG modules and their sub- and quotient modules
  * Operations on DG Submodules -- Sum,
    intersection, equality, and containment of DG submodules
  * DGAlgebra -- The class of all DGAlgebras

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2894:0.

DGModule -- The class of DG modules over a DG algebra
*****************************************************

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

A DGModule M over a DGAlgebra, A is a free graded
A.natural-module together with a differential that squares to zero and
satisfies the Leibniz rule against A.  Internally M is a hashtable with keys:

M.dgAlgebra — the ambient DGAlgebra.

M.natural — the underlying graded A.natural-module.

M.Degrees — the list of multi-degrees of the natural generators.

M.diff — a list of differentials, one per natural generator, each living in
M.natural in the appropriate homological degree.

New DGModules are constructed by freeDGModule,; the
differential on generators is set via setDiff.  Every
DGSubmodule, is also a DGModule (as a subtype); by contrast a
DGQuotientModule, is a separate type with a compatible
presentation.

+--------------------------------------------------------+
|i1 : R = ZZ/101[x]                                      |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                    }                    |
|      Underlying algebra => R[T   ]                     |
|                               1,1                      |
|      Differential => {x}                               |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                        |
|                                                        |
|o3 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, 0}                   |
|                                                        |
|o3 : DGModule                                           |
+--------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                        |
|o4 = {| 1 |, | 0 |}                                     |
|      | 0 |  | 1 |                                      |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : setDiff(M, {0, x * natGens#0})                     |
|                                                        |
|o5 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, | x |}               |
|                                   | 0 |                |
|                                                        |
|o5 : DGModule                                           |
+--------------------------------------------------------+
|i6 : isWellDefined M                                    |
|                                                        |
|o6 = true                                               |
+--------------------------------------------------------+
|i7 : M.Degrees                                          |
|                                                        |
|o7 = {{0, 0}, {1, 0}}                                   |
|                                                        |
|o7 : List                                               |
+--------------------------------------------------------+

See also
========

  * Building DG modules, submodules, and quotients
    -- The DGModule / DGSubmodule /
    DGQuotientModule hierarchy and its constructors
  * freeDGModule -- Construct a free DG module over a DG
    algebra
  * setDiff -- Install or replace the differential on a DG
    algebra
  * DGSubmodule -- The class of d-closed submodules of a DG
    module
  * DGQuotientModule -- The class of quotient DG
    modules M / S

Types of DGModule:
==================

  * DGSubmodule -- The class of d-closed submodules of a DG
    module

Functions and methods returning an object of class DGModule:
============================================================

  * adjoinGenerators -- Adjoin new free generators to
    a DG module with prescribed differentials
  * freeDGModule -- Construct a free DG module over a DG
    algebra
  * killCycles(DGModule) -- Adjoin free
    generators to kill the lowest nonvanishing homology of a DG module
  * koszulComplexDGM -- The Koszul complex of a module
    as a DG module
  * minimalSemifreeResolution -- Build a
    minimal semifree DG module resolution over a DG algebra
  * minimizeDGModule (missing documentation)
  * semifreeResolution -- Build a semifree DG module
    resolving a module over the base ring
  * setDiff(DGModule,List) -- Install the
    list of generator differentials on a free DG module

Methods that use an object of class DGModule:
=============================================

  * "adjoinGenerators(DGModule,List)" -- see adjoinGenerators,
    -- Adjoin new free generators to a DG module with
    prescribed differentials
  * components(DGModule) (missing documentation)
  * degrees(DGModule) -- Multi-degrees of the
    natural generators of a DG module
  * "dgComplex(DGModule)" -- see dgComplex, -- Package a DG
    algebra or DG module as a Complex of free base-ring modules
  * DGIdeal * DGModule (missing documentation)
  * DGModule ** DGModule -- Exterior tensor
    product of DG modules over DG algebras sharing a ground ring
  * DGModule ** Module -- Exterior tensor
    product of a DG module with an ordinary free module
  * "Module ** DGModule" -- see DGModule ** Module,
    -- Exterior tensor product of a DG module with an ordinary free
    module
  * DGModule ** Ring -- Base change of a DG module
    along a ring map
  * DGModule ++ DGModule (missing documentation)
  * DGModule / DGSubmodule -- Quotient DG
    module: M / S
  * "dgModuleMap(DGModule,DGModule,List)" -- see dgModuleMap,
    -- Construct a DGModuleMap from a matrix or from a list of
    image Vectors
  * "dgModuleMap(DGModule,DGModule,Matrix)" -- see dgModuleMap,
    -- Construct a DGModuleMap from a matrix or from a list of
    image Vectors
  * "map(DGModule,DGModule,ZZ)" -- see DGModuleMap == DGModuleMap,
    -- Elementary predicates and constructors for
    DGModuleMaps
  * "dgModuleSummary(DGModule)" -- see dgModuleSummary,
    -- Tabulate hom-degree-wise generator counts and free-rank counts for a DG
    module
  * "dgModuleSummary(DGModule,ZZ)" -- see dgModuleSummary,
    -- Tabulate hom-degree-wise generator counts and free-rank
    counts for a DG module
  * "dgQuotientModule(DGModule,DGSubmodule)" -- see dgQuotientModule,
    -- Construct the quotient DG module M / S
  * "dgSubmodule(DGModule,List)" -- see dgSubmodule, --
    Construct a d-closed submodule of a DG module
  * "dgSubmodule(DGModule,Matrix)" -- see dgSubmodule, --
    Construct a d-closed submodule of a DG module
  * diff(DGModule,Vector) -- Apply the DG
    module differential to an element
  * "differential(DGModule)" -- see differential, -- The
    list of generator differentials stored in a DG algebra or DG module
  * directSum(DGModule) (missing documentation)
  * "displayModuleBlockDiff(DGModule,List,List)" -- see
    displayModuleBlockDiff, -- Pretty-print the labeled
    block matrix of a DG module differential
  * "displayModuleBlockDiff(DGModule,ZZ)" -- see displayModuleBlockDiff,
    -- Pretty-print the labeled block matrix of a DG
    module differential
  * "ensureDGAlgebraCaches(DGModule)" -- see ensureDGAlgebraCaches,
    -- Guarantee that the standard cache sub-tables are
    present
  * "generatorDegrees(DGModule)" -- see generatorDegrees,
    -- The hom-degrees (and optional internal degrees) of the
    DG generators
  * "generatorTable(DGModule)" -- see generatorTable, --
    Display the generator list of a DG module with hom-degrees and
    differentials
  * getBasis(ZZ,DGModule) -- Basis of the
    hom-degree-n piece of a DG module
  * getBoundaryPreimage(DGModule,List)
    -- Lift a list of boundaries
    sharing a hom-degree through the module differential
  * getBoundaryPreimage(DGModule,Vector)
    -- Lift a boundary in a DG
    module to a preimage under the differential
  * HH DGModule -- The graded homology of a DG module as a
    module over HH(A)
  * "homologyModule(DGModule)" -- see HH DGModule, -- The
    graded homology of a DG module as a module over HH(A)
  * HH_ZZ DGModule -- The degree-n homology of a DG
    module as a module over the base ring
  * homologyClass(DGModule,Vector),
    -- The homology class of a cycle in a DG module
  * "identityDGModuleMap(DGModule)" -- see identityDGModuleMap,
    -- The identity DGModuleMap on a DG module
  * "invalidateDGAlgebraCache(DGModule)" -- see invalidateDGAlgebraCache,
    -- Discard cached derived data so that it is
    recomputed from scratch
  * isAcyclic(DGModule) -- Determine whether a
    DG module has vanishing positive-degree homology
  * "isDGSubmodule(DGModule,Matrix)" -- see isDGSubmodule,
    -- Test whether the image of an inclusion matrix is d-closed
  * "isFreeDGModule(DGModule)" -- see isFreeDGModule, --
    Is the underlying A.natural-module free?
  * isHomogeneous(DGModule) -- Test whether
    the underlying graded module is homogeneous
  * "isMinimalSemifreeResolution(DGModule)" -- see
    isMinimalSemifreeResolution, -- Test whether a
    semifree DG module is minimal over its DG algebra
  * "isValidDGModule(DGModule)" -- see isValidDGModule,
    -- Structural-invariant check on a DG module
  * isWellDefined(DGModule) -- Check that a
    DG module has correct structure and that its differential squares to zero
  * "isWellDefinedDifferential(DGModule)" -- see
    isWellDefinedDifferential, -- Semantic check
    that d^2 = 0 for a DG algebra or DG module
  * isZero(DGModule) -- Does the DG object have no
    natural generators?
  * "liftToDGModuleMap(DGModule,DGModule,List)" -- see liftToDGModuleMap,
    -- Lift an image of hom-degree-0 generators to a full
    DGModuleMap
  * "liftToDGModuleMap(DGModule,DGModule,Matrix)" -- see
    liftToDGModuleMap, -- Lift an image of hom-degree-0
    generators to a full DGModuleMap
  * "liftToDGModuleMap(DGModule,DGModule,Vector)" -- see
    liftToDGModuleMap, -- Lift an image of hom-degree-0
    generators to a full DGModuleMap
  * maxDegree(DGModule) -- Largest hom-degree
    present in a DG module
  * minimizeDGModule(DGModule) (missing documentation)
  * "moduleBlockDiff(DGModule,ZZ)" -- see moduleBlockDiff,
    -- The hom-degree-n differential of a DG module as a
    labeled block matrix
  * "moduleDifferential(ZZ,DGModule)" -- see moduleDifferential,
    -- The hom-degree-n differential of a DG module as a
    matrix over the base ring
  * net(DGModule) (missing documentation)
  * numgens(DGModule) -- Number of natural
    generators of a DG module (or sub- or quotient module)
  * "minimalPresentation(DGModule)" -- see prune(DGModule),
    -- Pruning a DG module is the identity
  * prune(DGModule) -- Pruning a DG module is the
    identity
  * rank(DGModule) -- Rank of the underlying free
    A.natural-module
  * ring(DGModule) (missing documentation)
  * toComplex(DGModule) -- Export a DG module
    to a Complex of free base-ring modules
  * toComplex(DGModule,ZZ) -- Export a DG
    module to a Complex with an explicit hom-degree bound
  * "underlyingAlgebra(DGModule)" -- see underlyingAlgebra,
    -- The graded-commutative algebra carrying the DG
    structure
  * "underlyingRing(DGModule)" -- see underlyingRing, --
    The commutative base ring of a DG algebra or DG module
  * "zeroDGModuleMap(DGModule,DGModule)" -- see zeroDGModuleMap,
    -- The zero DGModuleMap between two DG modules over a
    common algebra

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2935:0.

DGSubmodule -- The class of d-closed submodules of a DG module
**************************************************************

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

A DGSubmodule S of a DGModule, M is a free A.natural-module
together with an inclusion S.inclusion : S → M of DGModules whose column span
in M.natural is closed under the differential of M. DGSubmodule is a subtype of
DGModule, so every DG-module operation applies to submodules
as well.

Beyond the DGModule keys, a DGSubmodule carries:

S.ambient — the enclosing DGModule M.

S.inclusion — a DGModuleMap, S → M; use inclusion,
to access it.

New DGSubmodules are constructed by dgSubmodule, which
takes either an inclusion matrix or a list of generators, and d-saturates the
input automatically.  See Operations on DG Submodules,
for the lattice operations (sum, intersection, equality,
containment).

+---------------------------------------+
|i1 : R = ZZ/101[x]                     |
|                                       |
|o1 = R                                 |
|                                       |
|o1 : PolynomialRing                    |
+---------------------------------------+
|i2 : A = koszulComplexDGA R            |
|                                       |
|o2 = {Ring => R                    }   |
|      Underlying algebra => R[T   ]    |
|                               1,1     |
|      Differential => {x}              |
|                                       |
|o2 : DGAlgebra                         |
+---------------------------------------+
|i3 : M = freeDGModule(A, {0})          |
|                                       |
|o3 = {Base ring => R               }   |
|      DG algebra => R[T   ]            |
|                       1,1             |
|                                 1     |
|      Natural module => (R[T   ])      |
|                            1,1        |
|      Generator degrees => {{0, 0}}    |
|      Differentials on gens => {0}     |
|                                       |
|o3 : DGModule                          |
+---------------------------------------+
|i4 : S = dgSubmodule(M, id_(M.natural))|
|                                       |
|o4 = DGSubmodule of ambient DGModule   |
|     Degrees  => {{0, 0}}              |
|                          1            |
|     natural  => (R[T   ])             |
|                     1,1               |
|     inclusion => | 1 |                |
|                                       |
|o4 : DGSubmodule                       |
+---------------------------------------+
|i5 : ambient S === M                   |
|                                       |
|o5 = true                              |
+---------------------------------------+
|i6 : source inclusion S === S          |
|                                       |
|o6 = true                              |
+---------------------------------------+
|i7 : target inclusion S === M          |
|                                       |
|o7 = true                              |
+---------------------------------------+

See also
========

  * Building DG modules, submodules, and quotients
    -- The DGModule / DGSubmodule /
    DGQuotientModule hierarchy and its constructors
  * Operations on DG Submodules -- Sum,
    intersection, equality, and containment of DG submodules
  * dgSubmodule -- Construct a d-closed submodule of a DG
    module
  * DGModule -- The class of DG modules over a DG algebra
  * inclusion -- Accessors for the ambient object, inclusion,
    projection, and killed submodule

Functions and methods returning an object of class DGSubmodule:
===============================================================

  * dgSubmodule -- Construct a d-closed submodule of a DG
    module
  * intersect(DGSubmodule,DGSubmodule)
    -- Intersection of two DG
    submodules of a common ambient

Methods that use an object of class DGSubmodule:
================================================

  * "ambient(DGSubmodule)" -- see ambient, -- Accessors for the
    ambient object, inclusion, projection, and killed submodule
  * "inclusion(DGSubmodule)" -- see ambient, -- Accessors for
    the ambient object, inclusion, projection, and killed submodule
  * annihilator(DGSubmodule) -- The DG
    ideal of A annihilating a DG submodule
  * "degrees(DGSubmodule)" -- see degrees(DGModule),
    -- Multi-degrees of the natural generators of a DG
    module
  * DGIdeal * DGSubmodule (missing documentation)
  * DGModule / DGSubmodule -- Quotient DG
    module: M / S
  * "dgQuotientModule(DGModule,DGSubmodule)" -- see dgQuotientModule,
    -- Construct the quotient DG module M / S
  * DGSubmodule ** Module -- Exterior tensor
    product of a DG submodule with an ordinary free module
  * "Module ** DGSubmodule" -- see DGSubmodule ** Module,
    -- Exterior tensor product of a DG submodule with an
    ordinary free module
  * DGSubmodule ** Ring -- Base change of a DG
    submodule along a ring map
  * DGSubmodule + DGSubmodule -- Sum of two
    DG submodules of a common ambient
  * DGSubmodule == DGSubmodule -- Equality
    and containment of DG submodules
  * "isSubset(DGSubmodule,DGSubmodule)" -- see DGSubmodule == DGSubmodule,
    -- Equality and containment of DG
    submodules
  * "isFreeDGModule(DGSubmodule)" -- see isFreeDGModule,
    -- Is the underlying A.natural-module free?
  * "isHomogeneous(DGSubmodule)" -- see isHomogeneous(DGModule),
    -- Test whether the underlying graded module
    is homogeneous
  * isWellDefined(DGSubmodule) -- Check
    that a DG submodule is d-closed in its ambient DG module
  * "isZero(DGSubmodule)" -- see isZero(DGModule),
    -- Does the DG object have no natural generators?
  * module(DGSubmodule) (missing documentation)
  * net(DGSubmodule) (missing documentation)
  * "numgens(DGSubmodule)" -- see numgens(DGModule),
    -- Number of natural generators of a DG module (or
    sub- or quotient module)
  * "minimalPresentation(DGSubmodule)" -- see prune(DGSubmodule),
    -- Trim a DG submodule to a minimal generating set
    of its inclusion
  * prune(DGSubmodule) -- Trim a DG submodule to
    a minimal generating set of its inclusion
  * "rank(DGSubmodule)" -- see rank(DGModule), --
    Rank of the underlying free A.natural-module
  * super(DGSubmodule) -- Ambient DGModule,
    cover, and relation matrix of a DG sub- or quotient module

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:2977:0.

DGQuotientModule -- The class of quotient DG modules M / S
**********************************************************

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

A DGQuotientModule Q = M / S is the cokernel of the inclusion S.inclusion : S →
M, equipped with the induced differential.  Unlike DGSubmodule,
DGQuotientModule is NOT a subtype of DGModule,:
its .natural is a cokernel module, which does not support the free-module
operations (rank, basis by index) that DG algorithms assume on a generic
DGModule.

Beyond the DGModule-like keys (.dgAlgebra, .natural, .Degrees, .diff), a
DGQuotientModule carries:

Q.ambient — the DGModule M from which Q was built; accessible via
ambient (Macaulay2Doc).

Q.subDGModule — the killed submodule S; accessible via subDGModule.

Q.projection — the quotient map M → Q as a DGModuleMap,;
accessible via projection.

New DGQuotientModules are built by dgQuotientModule, or
the shorthand M / S.

+------------------------------------+
|i1 : R = ZZ/101[x]                  |
|                                    |
|o1 = R                              |
|                                    |
|o1 : PolynomialRing                 |
+------------------------------------+
|i2 : A = koszulComplexDGA R         |
|                                    |
|o2 = {Ring => R                    }|
|      Underlying algebra => R[T   ] |
|                               1,1  |
|      Differential => {x}           |
|                                    |
|o2 : DGAlgebra                      |
+------------------------------------+
|i3 : M = freeDGModule(A, {0})       |
|                                    |
|o3 = {Base ring => R               }|
|      DG algebra => R[T   ]         |
|                       1,1          |
|                                 1  |
|      Natural module => (R[T   ])   |
|                            1,1     |
|      Generator degrees => {{0, 0}} |
|      Differentials on gens => {0}  |
|                                    |
|o3 : DGModule                       |
+------------------------------------+
|i4 : Z = dgSubmodule(M, {})         |
|                                    |
|o4 = DGSubmodule of ambient DGModule|
|     Degrees  => {}                 |
|     natural  => 0                  |
|     inclusion => 0                 |
|                                    |
|o4 : DGSubmodule                    |
+------------------------------------+
|i5 : Q = M / Z                      |
|                                    |
|o5 = DGQuotientModule Q = M / S     |
|                          1         |
|     Q.natural = (R[T   ])          |
|                     1,1            |
|     Degrees   = {{0, 0}}           |
|                                    |
|o5 : DGQuotientModule               |
+------------------------------------+
|i6 : instance(Q, DGQuotientModule)  |
|                                    |
|o6 = true                           |
+------------------------------------+
|i7 : ambient Q === M                |
|                                    |
|o7 = true                           |
+------------------------------------+
|i8 : subDGModule Q === Z            |
|                                    |
|o8 = true                           |
+------------------------------------+
|i9 : source projection Q === M      |
|                                    |
|o9 = true                           |
+------------------------------------+
|i10 : target projection Q === Q     |
|                                    |
|o10 = true                          |
+------------------------------------+

See also
========

  * Building DG modules, submodules, and quotients
    -- The DGModule / DGSubmodule /
    DGQuotientModule hierarchy and its constructors
  * Module-like operations on DG modules
    -- Basic queries (generators, rank, degrees, homogeneity) extended
    to DG modules and their sub- and quotient modules
  * dgQuotientModule -- Construct the quotient DG
    module M / S
  * DGModule / DGSubmodule -- Quotient DG
    module: M / S

Functions and methods returning an object of class DGQuotientModule:
====================================================================

  * dgQuotientModule -- Construct the quotient DG
    module M / S

Methods that use an object of class DGQuotientModule:
=====================================================

  * "ambient(DGQuotientModule)" -- see ambient, -- Accessors for
    the ambient object, inclusion, projection, and killed submodule
  * "projection(DGQuotientModule)" -- see ambient, -- Accessors
    for the ambient object, inclusion, projection, and killed submodule
  * "subDGModule(DGQuotientModule)" -- see ambient, -- Accessors
    for the ambient object, inclusion, projection, and killed submodule
  * annihilator(DGQuotientModule), --
    The DG ideal of A annihilating a DG quotient module
  * "degrees(DGQuotientModule)" -- see degrees(DGModule),
    -- Multi-degrees of the natural generators of a DG
    module
  * DGQuotientModule ** Module, --
    Exterior tensor product of a DG quotient module with an ordinary free
    module
  * "Module ** DGQuotientModule" -- see DGQuotientModule ** Module,
    -- Exterior tensor product of a DG quotient
    module with an ordinary free module
  * DGQuotientModule ** Ring -- Base
    change of a DG quotient module along a ring map
  * diff(DGQuotientModule,Vector),
    -- Apply the induced differential on a DG quotient module to an element
  * HH DGQuotientModule -- The graded homology of a
    DG quotient module
  * "homologyModule(DGQuotientModule)" -- see HH DGQuotientModule,
    -- The graded homology of a DG quotient module
  * HH_ZZ DGQuotientModule -- The degree-n
    homology of a DG quotient module
  * isAcyclic(DGQuotientModule), --
    Determine whether a DG quotient module has vanishing positive-degree
    homology
  * "isHomogeneous(DGQuotientModule)" -- see isHomogeneous(DGModule),
    -- Test whether the underlying graded module
    is homogeneous
  * isWellDefined(DGQuotientModule),
    -- Check that a DG quotient module has a well-defined differential
  * "isZero(DGQuotientModule)" -- see isZero(DGModule),
    -- Does the DG object have no natural generators?
  * maxDegree(DGQuotientModule), --
    Largest hom-degree present in a DG quotient module
  * net(DGQuotientModule) (missing documentation)
  * "numgens(DGQuotientModule)" -- see numgens(DGModule),
    -- Number of natural generators of a DG module (or
    sub- or quotient module)
  * "minimalPresentation(DGQuotientModule)" -- see
    prune(DGQuotientModule), -- Minimize the
    presentation of a DG quotient module
  * prune(DGQuotientModule) -- Minimize the
    presentation of a DG quotient module
  * "cover(DGQuotientModule)" -- see super(DGSubmodule),
    -- Ambient DGModule, cover, and relation matrix of
    a DG sub- or quotient module
  * "relations(DGQuotientModule)" -- see super(DGSubmodule),
    -- Ambient DGModule, cover, and relation matrix of
    a DG sub- or quotient module
  * "super(DGQuotientModule)" -- see super(DGSubmodule),
    -- Ambient DGModule, cover, and relation matrix of
    a DG sub- or quotient module
  * toComplex(DGQuotientModule), --
    Export a DG quotient module to a Complex

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3024:0.

freeDGModule -- Construct a free DG module over a DG algebra
************************************************************

  * Usage:
        M = freeDGModule(A, degList)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * degList, a list (Macaulay2Doc), of multi-degrees.  Each
        entry is either an integer (interpreted as a homological degree with
        trivial internal degree) or a list whose first entry is the homological
        degree and whose remaining entries are internal degrees.  Short lists
        are right-padded with zeros to match the length of a degree in degrees
        A.natural.
  * Outputs:
      * M, an instance of the type DGModule, A DGModule whose
        .natural is the graded free A.natural-module of rank #degList with the
        specified generator degrees, and whose differential is initialized to
        zero on every generator.

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

The differential is initially set to zero on every generator, and is customized
afterward via setDiff.  Because the constructor returns a free
DGModule, the result can serve as a building block for
semifree resolutions (see adjoinGenerators, and
semifreeResolution) or as the starting point for a
hand-built DG module, as illustrated below.

Here we build the 2-periodic minimal free resolution of the residue field over
the hypersurface R = k[x]/(x^2) — the prototypical Eisenbud matrix
factorization — as an infinite semifree DG module over the Koszul DG algebra:

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x] / ideal(x^2)                                                  |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o2 = {Ring => R                    }                                         |
|      Underlying algebra => R[T   ]                                          |
|                               1,1                                           |
|      Differential => {x}                                                    |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : F = freeDGModule(A, toList(0..4))                                       |
|                                                                             |
|o3 = {Base ring => R                                               }         |
|      DG algebra => R[T   ]                                                  |
|                       1,1                                                   |
|                                 5                                           |
|      Natural module => (R[T   ])                                            |
|                            1,1                                              |
|      Generator degrees => {{0, 0}, {1, 0}, {2, 0}, {3, 0}, {4, 0}}          |
|      Differentials on gens => {0, 0, 0, 0, 0}                               |
|                                                                             |
|o3 : DGModule                                                                |
+-----------------------------------------------------------------------------+
|i4 : natGens = apply(rank F.natural, i -> (F.natural)_i)                     |
|                                                                             |
|o4 = {| 1 |, | 0 |, | 0 |, | 0 |, | 0 |}                                     |
|      | 0 |  | 1 |  | 0 |  | 0 |  | 0 |                                      |
|      | 0 |  | 0 |  | 1 |  | 0 |  | 0 |                                      |
|      | 0 |  | 0 |  | 0 |  | 1 |  | 0 |                                      |
|      | 0 |  | 0 |  | 0 |  | 0 |  | 1 |                                      |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : setDiff(F, {0, x * natGens#0, x * natGens#1, x * natGens#2, x *         |
|                                                                             |
|o5 = {Base ring => R                                               }         |
|      DG algebra => R[T   ]                                                  |
|                       1,1                                                   |
|                                 5                                           |
|      Natural module => (R[T   ])                                            |
|                            1,1                                              |
|      Generator degrees => {{0, 0}, {1, 0}, {2, 0}, {3, 0}, {4, 0}}          |
|      Differentials on gens => {0, | x |, | 0 |, | 0 |, | 0 |}               |
|                                   | 0 |  | x |  | 0 |  | 0 |                |
|                                   | 0 |  | 0 |  | x |  | 0 |                |
|                                   | 0 |  | 0 |  | 0 |  | x |                |
|                                   | 0 |  | 0 |  | 0 |  | 0 |                |
|                                                                             |
|o5 : DGModule                                                                |
|-----------------------------------------------------------------------------|
|natGens#3})                                                                  |
+-----------------------------------------------------------------------------+
|i6 : apply(1..4, n -> moduleDifferential(n, F))                              |
|                                                                             |
|o6 = (| x x |, {1} | -x 0 |, {1} | -x 0 |, {1} | -x 0 |)                     |
|               {0} | x  x |  {0} | x  x |  {0} | x  x |                      |
|                                                                             |
|o6 : Sequence                                                                |
+-----------------------------------------------------------------------------+

The differential alternates between multiplication by x in every degree,
matching the classical 2-periodic resolution of the residue field.  Its
homology is concentrated in degree zero:

+-------------------------------------------+
|i7 : apply(0..3, n -> prune homology(n, F))|
|                                           |
|o7 = (cokernel | x |, cokernel | x |, 0, 0)|
|                                           |
|o7 : Sequence                              |
+-------------------------------------------+

More elaborate differentials are possible once multiple generators sit in
overlapping hom-degrees.  Here is a rank-3 toy example where F_1 has two
generators and d_1 sends them to x and y respectively, recovering the
truncation of the Koszul complex on (x, y):

+------------------------------------------------------+
|i8 : S = QQ[x, y]                                     |
|                                                      |
|o8 = S                                                |
|                                                      |
|o8 : PolynomialRing                                   |
+------------------------------------------------------+
|i9 : AS = koszulComplexDGA S                          |
|                                                      |
|o9 = {Ring => S                          }            |
|      Underlying algebra => S[T   ..T   ]             |
|                               1,1   1,2              |
|      Differential => {x, y}                          |
|                                                      |
|o9 : DGAlgebra                                        |
+------------------------------------------------------+
|i10 : G = freeDGModule(AS, {0, 1, 1})                 |
|                                                      |
|o10 = {Base ring => S                               } |
|       DG algebra => S[T   ..T   ]                    |
|                        1,1   1,2                     |
|                                        3             |
|       Natural module => (S[T   ..T   ])              |
|                             1,1   1,2                |
|       Generator degrees => {{0, 0}, {1, 0}, {1, 0}}  |
|       Differentials on gens => {0, 0, 0}             |
|                                                      |
|o10 : DGModule                                        |
+------------------------------------------------------+
|i11 : natG = apply(rank G.natural, i -> (G.natural)_i)|
|                                                      |
|o11 = {| 1 |, | 0 |, | 0 |}                           |
|       | 0 |  | 1 |  | 0 |                            |
|       | 0 |  | 0 |  | 1 |                            |
|                                                      |
|o11 : List                                            |
+------------------------------------------------------+
|i12 : setDiff(G, {0, x * natG#0, y * natG#0})         |
|                                                      |
|o12 = {Base ring => S                               } |
|       DG algebra => S[T   ..T   ]                    |
|                        1,1   1,2                     |
|                                        3             |
|       Natural module => (S[T   ..T   ])              |
|                             1,1   1,2                |
|       Generator degrees => {{0, 0}, {1, 0}, {1, 0}}  |
|       Differentials on gens => {0, | x |, | y |}     |
|                                    | 0 |  | 0 |      |
|                                    | 0 |  | 0 |      |
|                                                      |
|o12 : DGModule                                        |
+------------------------------------------------------+
|i13 : moduleDifferential(1, G)                        |
|                                                      |
|o13 = | x y x y |                                     |
|                                                      |
|              1      4                                |
|o13 : Matrix S  <-- S                                 |
+------------------------------------------------------+

Internal degrees from a multi-graded base ring are inherited; a plain
homological degree is padded with zeros to match.

+----------------------------------------------------+
|i14 : Rg = ZZ/101[x, y, Degrees => {{1, 0}, {0, 1}}]|
|                                                    |
|o14 = Rg                                            |
|                                                    |
|o14 : PolynomialRing                                |
+----------------------------------------------------+
|i15 : Ag = koszulComplexDGA Rg                      |
|                                                    |
|o15 = {Ring => Rg                          }        |
|       Underlying algebra => Rg[T   ..T   ]         |
|                                 1,1   1,2          |
|       Differential => {x, y}                       |
|                                                    |
|o15 : DGAlgebra                                     |
+----------------------------------------------------+
|i16 : Mg = freeDGModule(Ag, {{0, 0, 0}, {1, 0, 0}}) |
|                                                    |
|o16 = {Base ring => Rg                            } |
|       DG algebra => Rg[T   ..T   ]                 |
|                         1,1   1,2                  |
|                                         2          |
|       Natural module => (Rg[T   ..T   ])           |
|                              1,1   1,2             |
|       Generator degrees => {{0, 0, 0}, {1, 0, 0}}  |
|       Differentials on gens => {0, 0}              |
|                                                    |
|o16 : DGModule                                      |
+----------------------------------------------------+
|i17 : degrees Mg                                    |
|                                                    |
|o17 = {{0, 0, 0}, {1, 0, 0}}                        |
|                                                    |
|o17 : List                                          |
+----------------------------------------------------+

The empty-list form gives the zero DG module.

+-----------------------------------+
|i18 : M0 = freeDGModule(A, {})     |
|                                   |
|o18 = {Base ring => R             }|
|  DG algebra => R[T   ]            |
|                   1,1             |
|  Natural module => 0              |
|  Generator degrees => {}          |
|  Differentials on gens => {}      |
|                                   |
|o18 : DGModule                     |
+-----------------------------------+
|i19 : isZero M0                    |
|                                   |
|o19 = true                         |
+-----------------------------------+

See also
========

  * Building DG modules, submodules, and quotients
    -- The DGModule / DGSubmodule /
    DGQuotientModule hierarchy and its constructors
  * DGModule -- The class of DG modules over a DG algebra
  * setDiff -- Install or replace the differential on a DG
    algebra
  * adjoinGenerators -- Adjoin new free generators to
    a DG module with prescribed differentials
  * semifreeResolution -- Build a semifree DG module
    resolving a module over the base ring
  * isWellDefined(DGModule) -- Check that a
    DG module has correct structure and that its differential squares to zero

Ways to use freeDGModule:
=========================

  * "freeDGModule(DGAlgebra,List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3106:0.

dgSubmodule -- Construct a d-closed submodule of a DG module
************************************************************

  * Usage:
        S = dgSubmodule(M, incMat)
        S = dgSubmodule(M, gs)
  * Inputs:
      * M, an instance of the type DGModule,
      * incMat, a matrix (Macaulay2Doc), with target M.natural,
        whose columns are proposed generators of the submodule.
      * gs, a list (Macaulay2Doc), of elements of M.natural (as
        Vectors, 1-column Matrices, or anything coercible to M.natural).  The
        empty list gives the zero submodule.
  * Outputs:
      * S, an instance of the type DGSubmodule, The
        smallest d-closed submodule of M containing the columns of incMat
        (respectively the elements of gs).

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

The constructor iteratively adjoins the M-differentials of the current
generators until the column span is closed, then builds the lifted differential
on the resulting free module.  If d-closure fails to stabilize within 200
iterations, an error is raised — in practice this only happens if the ambient
module has unbounded homological degree and the seed is chosen poorly.

+---------------------------------------+
|i1 : R = ZZ/101[x]                     |
|                                       |
|o1 = R                                 |
|                                       |
|o1 : PolynomialRing                    |
+---------------------------------------+
|i2 : A = koszulComplexDGA R            |
|                                       |
|o2 = {Ring => R                    }   |
|      Underlying algebra => R[T   ]    |
|                               1,1     |
|      Differential => {x}              |
|                                       |
|o2 : DGAlgebra                         |
+---------------------------------------+
|i3 : M = freeDGModule(A, {0})          |
|                                       |
|o3 = {Base ring => R               }   |
|      DG algebra => R[T   ]            |
|                       1,1             |
|                                 1     |
|      Natural module => (R[T   ])      |
|                            1,1        |
|      Generator degrees => {{0, 0}}    |
|      Differentials on gens => {0}     |
|                                       |
|o3 : DGModule                          |
+---------------------------------------+
|i4 : S = dgSubmodule(M, id_(M.natural))|
|                                       |
|o4 = DGSubmodule of ambient DGModule   |
|     Degrees  => {{0, 0}}              |
|                          1            |
|     natural  => (R[T   ])             |
|                     1,1               |
|     inclusion => | 1 |                |
|                                       |
|o4 : DGSubmodule                       |
+---------------------------------------+
|i5 : instance(S, DGSubmodule)          |
|                                       |
|o5 = true                              |
+---------------------------------------+
|i6 : ambient S === M                   |
|                                       |
|o6 = true                              |
+---------------------------------------+
|i7 : isWellDefined S                   |
|                                       |
|o7 = true                              |
+---------------------------------------+

The list form coerces each entry to an element of M.natural; passing the empty
list produces the zero submodule.

+---------------------------------------+
|i8 : Z = dgSubmodule(M, {})            |
|                                       |
|o8 = DGSubmodule of ambient DGModule   |
|     Degrees  => {}                    |
|     natural  => 0                     |
|     inclusion => 0                    |
|                                       |
|o8 : DGSubmodule                       |
+---------------------------------------+
|i9 : numcols (inclusion Z).natural == 0|
|                                       |
|o9 = true                              |
+---------------------------------------+
|i10 : isZero Z                         |
|                                       |
|o10 = true                             |
+---------------------------------------+

d-closure is performed automatically.  Seeding with a non-closed generator
pulls in its M-differential:

+-----------------------------------------------------------+
|i11 : M2 = freeDGModule(A, {0, 1})                         |
|                                                           |
|o11 = {Base ring => R                       }              |
|       DG algebra => R[T   ]                               |
|                        1,1                                |
|                                  2                        |
|       Natural module => (R[T   ])                         |
|                             1,1                           |
|       Generator degrees => {{0, 0}, {1, 0}}               |
|       Differentials on gens => {0, 0}                     |
|                                                           |
|o11 : DGModule                                             |
+-----------------------------------------------------------+
|i12 : natGens = apply(rank M2.natural, i -> (M2.natural)_i)|
|                                                           |
|o12 = {| 1 |, | 0 |}                                       |
|       | 0 |  | 1 |                                        |
|                                                           |
|o12 : List                                                 |
+-----------------------------------------------------------+
|i13 : setDiff(M2, {0, x * natGens#0})                      |
|                                                           |
|o13 = {Base ring => R                       }              |
|       DG algebra => R[T   ]                               |
|                        1,1                                |
|                                  2                        |
|       Natural module => (R[T   ])                         |
|                             1,1                           |
|       Generator degrees => {{0, 0}, {1, 0}}               |
|       Differentials on gens => {0, | x |}                 |
|                                    | 0 |                  |
|                                                           |
|o13 : DGModule                                             |
+-----------------------------------------------------------+
|i14 : Anat = A.natural                                     |
|                                                           |
|o14 = Anat                                                 |
|                                                           |
|o14 : PolynomialRing, 1 skew commutative variable(s)       |
+-----------------------------------------------------------+
|i15 : seed = (id_(M2.natural))_{1}                         |
|                                                           |
|o15 = {0, 0} | 0 |                                         |
|      {1, 0} | 1 |                                         |
|                                                           |
|                 2         1                               |
|o15 : Matrix Anat  <-- Anat                                |
+-----------------------------------------------------------+
|i16 : S2 = dgSubmodule(M2, seed)                           |
|                                                           |
|o16 = DGSubmodule of ambient DGModule                      |
|      Degrees  => {{1, 0}, {0, 0}}                         |
|                      2                                    |
|      natural  => Anat                                     |
|      inclusion => {0, 0} | 0 x |                          |
|                   {1, 0} | 1 0 |                          |
|                                                           |
|o16 : DGSubmodule                                          |
+-----------------------------------------------------------+
|i17 : xe0 = (id_(M2.natural))_{0} * matrix {{x_Anat}}      |
|                                                           |
|o17 = {0, 0} | x |                                         |
|      {1, 0} | 0 |                                         |
|                                                           |
|                 2         1                               |
|o17 : Matrix Anat  <-- Anat                                |
+-----------------------------------------------------------+
|i18 : incMat = (inclusion S2).natural                      |
|                                                           |
|o18 = {0, 0} | 0 x |                                       |
|      {1, 0} | 1 0 |                                       |
|                                                           |
|                 2         2                               |
|o18 : Matrix Anat  <-- Anat                                |
+-----------------------------------------------------------+
|i19 : (xe0 - incMat * (xe0 // incMat)) == 0                |
|                                                           |
|o19 = true                                                 |
+-----------------------------------------------------------+

In a richer setting, consider the minimal semifree resolution of the residue
field over the complete intersection R = QQ[x, y]/(x^2, y^2).  Seeding the
submodule with the hom-degree-2 natural generators, d-closure automatically
pulls in the hom-degree-4 generators that sit below them in the Koszul-style
differential:

+-----------------------------------------------------------------------------+
|i20 : S = QQ[x, y] / ideal(x^2, y^2)                                         |
|                                                                             |
|o20 = S                                                                      |
|                                                                             |
|o20 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i21 : B = koszulComplexDGA S                                                 |
|                                                                             |
|o21 = {Ring => S                          }                                  |
|       Underlying algebra => S[T   ..T   ]                                   |
|                                1,1   1,2                                    |
|       Differential => {x, y}                                                |
|                                                                             |
|o21 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i22 : Mdg = minimalSemifreeResolution(B, S^1 / ideal(x, y), EndDegree => 3)  |
|                                                                             |
|o22 = {Base ring => S                                                        |
|       DG algebra => S[T   ..T   ]                                           |
|                        1,1   1,2                                            |
|                                        6                                    |
|       Natural module => (S[T   ..T   ])                                     |
|                             1,1   1,2                                       |
|       Generator degrees => {{0, 0}, {2, 2}, {2, 2}, {4, 4}, {4, 4}, {4, 4}} |
|       Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |, |     0    |,|
|                                    |     0    |  |     0    |  | xT_(1,1) | |
|                                    |     0    |  |     0    |  |     0    | |
|                                    |     0    |  |     0    |  |     0    | |
|                                    |     0    |  |     0    |  |     0    | |
|                                    |     0    |  |     0    |  |     0    | |
|                                                                             |
|o22 : DGModule                                                               |
|-----------------------------------------------------------------------------|
|                           }                                                 |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
||     0    |, |     0    |}                                                  |
|| yT_(1,2) |  |     0    |                                                   |
|| xT_(1,1) |  | yT_(1,2) |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
+-----------------------------------------------------------------------------+
|i23 : homDegs = apply(Mdg.Degrees, d -> d#0)                                 |
|                                                                             |
|o23 = {0, 2, 2, 4, 4, 4}                                                     |
|                                                                             |
|o23 : List                                                                   |
+-----------------------------------------------------------------------------+
|i24 : pos2 = positions(Mdg.Degrees, d -> d#0 == 2)                           |
|                                                                             |
|o24 = {1, 2}                                                                 |
|                                                                             |
|o24 : List                                                                   |
+-----------------------------------------------------------------------------+
|i25 : seedHi = (id_(Mdg.natural))_pos2                                       |
|                                                                             |
|o25 = {0, 0} | 0 0 |                                                         |
|      {2, 2} | 1 0 |                                                         |
|      {2, 2} | 0 1 |                                                         |
|      {4, 4} | 0 0 |                                                         |
|      {4, 4} | 0 0 |                                                         |
|      {4, 4} | 0 0 |                                                         |
|                                                                             |
|                            6                    2                           |
|o25 : Matrix (S[T   ..T   ])  <-- (S[T   ..T   ])                            |
|                 1,1   1,2            1,1   1,2                              |
+-----------------------------------------------------------------------------+
|i26 : Shi = dgSubmodule(Mdg, seedHi)                                         |
|                                                                             |
|o26 = DGSubmodule of ambient DGModule                                        |
|      Degrees  => {{2, 2}, {2, 2}, {1, 2}, {1, 2}}                           |
|                                 4                                           |
|      natural  => (S[T   ..T   ])                                            |
|                      1,1   1,2                                              |
|      inclusion => {0, 0} | 0 0 xT_(1,1) yT_(1,2) |                          |
|                   {2, 2} | 1 0 0        0        |                          |
|                   {2, 2} | 0 1 0        0        |                          |
|                   {4, 4} | 0 0 0        0        |                          |
|                   {4, 4} | 0 0 0        0        |                          |
|                   {4, 4} | 0 0 0        0        |                          |
|                                                                             |
|o26 : DGSubmodule                                                            |
+-----------------------------------------------------------------------------+
|i27 : apply(Shi.Degrees, d -> d#0)                                           |
|                                                                             |
|o27 = {2, 2, 1, 1}                                                           |
|                                                                             |
|o27 : List                                                                   |
+-----------------------------------------------------------------------------+
|i28 : isWellDefined Shi                                                      |
|                                                                             |
|o28 = true                                                                   |
+-----------------------------------------------------------------------------+

Caveat
======

The target of the inclusion matrix must be M.natural on the nose (object
identity, not just isomorphism).  This catches common shape mistakes up front —
for example, building matrix {{a, b}} for a rank-n ambient produces a 1×2
matrix whose target is rank 1, not rank n.

See also
========

  * Building DG modules, submodules, and quotients
    -- The DGModule / DGSubmodule /
    DGQuotientModule hierarchy and its constructors
  * Operations on DG Submodules -- Sum,
    intersection, equality, and containment of DG submodules
  * DGSubmodule -- The class of d-closed submodules of a DG
    module
  * inclusion -- Accessors for the ambient object, inclusion,
    projection, and killed submodule
  * isWellDefined(DGModule) -- Check that a
    DG module has correct structure and that its differential squares to zero

Ways to use dgSubmodule:
========================

  * "dgSubmodule(DGModule,List)"
  * "dgSubmodule(DGModule,Matrix)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3197:0.

dgQuotientModule -- Construct the quotient DG module M / S
**********************************************************

  * Usage:
        Q = dgQuotientModule(M, S)
  * Inputs:
      * M, an instance of the type DGModule,
      * S, an instance of the type DGSubmodule, With
        S.ambient === M.
  * Outputs:
      * Q, an instance of the type DGQuotientModule,
        The cokernel of S.inclusion.natural equipped with the induced
        differential.

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

The shorthand M / S calls this constructor.  The resulting Q records the
ambient M (via ambient (Macaulay2Doc)), the killed submodule S
(via subDGModule), and the quotient map M → Q (via
projection).

+------------------------------------+
|i1 : R = ZZ/101[x]                  |
|                                    |
|o1 = R                              |
|                                    |
|o1 : PolynomialRing                 |
+------------------------------------+
|i2 : A = koszulComplexDGA R         |
|                                    |
|o2 = {Ring => R                    }|
|      Underlying algebra => R[T   ] |
|                               1,1  |
|      Differential => {x}           |
|                                    |
|o2 : DGAlgebra                      |
+------------------------------------+
|i3 : M = freeDGModule(A, {0})       |
|                                    |
|o3 = {Base ring => R               }|
|      DG algebra => R[T   ]         |
|                       1,1          |
|                                 1  |
|      Natural module => (R[T   ])   |
|                            1,1     |
|      Generator degrees => {{0, 0}} |
|      Differentials on gens => {0}  |
|                                    |
|o3 : DGModule                       |
+------------------------------------+
|i4 : Z = dgSubmodule(M, {})         |
|                                    |
|o4 = DGSubmodule of ambient DGModule|
|     Degrees  => {}                 |
|     natural  => 0                  |
|     inclusion => 0                 |
|                                    |
|o4 : DGSubmodule                    |
+------------------------------------+
|i5 : Q = dgQuotientModule(M, Z)     |
|                                    |
|o5 = DGQuotientModule Q = M / S     |
|                          1         |
|     Q.natural = (R[T   ])          |
|                     1,1            |
|     Degrees   = {{0, 0}}           |
|                                    |
|o5 : DGQuotientModule               |
+------------------------------------+
|i6 : instance(Q, DGQuotientModule)  |
|                                    |
|o6 = true                           |
+------------------------------------+
|i7 : ambient Q === M                |
|                                    |
|o7 = true                           |
+------------------------------------+
|i8 : subDGModule Q === Z            |
|                                    |
|o8 = true                           |
+------------------------------------+

Quotienting by the zero submodule gives a DGQuotientModule whose underlying
cokernel is isomorphic to M.natural; quotienting by the whole ambient yields
the zero DGQuotientModule.

+-------------------------------------------+
|i9 : Sfull = dgSubmodule(M, id_(M.natural))|
|                                           |
|o9 = DGSubmodule of ambient DGModule       |
|     Degrees  => {{0, 0}}                  |
|                          1                |
|     natural  => (R[T   ])                 |
|                     1,1                   |
|     inclusion => | 1 |                    |
|                                           |
|o9 : DGSubmodule                           |
+-------------------------------------------+
|i10 : Qzero = M / Sfull                    |
|                                           |
|o10 = DGQuotientModule Q = M / S           |
|      Q.natural = cokernel | 1 |           |
|      Degrees   = {{0, 0}}                 |
|                                           |
|o10 : DGQuotientModule                     |
+-------------------------------------------+
|i11 : isZero Qzero                         |
|                                           |
|o11 = true                                 |
+-------------------------------------------+

Caveat
======

S.ambient must equal M as an object (===), not merely be isomorphic.  This
enforces a strict lattice-of-submodules discipline on the resulting quotient.

See also
========

  * Building DG modules, submodules, and quotients
    -- The DGModule / DGSubmodule /
    DGQuotientModule hierarchy and its constructors
  * DGModule / DGSubmodule -- Quotient DG
    module: M / S
  * DGQuotientModule -- The class of quotient DG
    modules M / S
  * projection -- Accessors for the ambient object, inclusion,
    projection, and killed submodule
  * subDGModule -- Accessors for the ambient object, inclusion,
    projection, and killed submodule

Ways to use dgQuotientModule:
=============================

  * "dgQuotientModule(DGModule,DGSubmodule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3248:0.

DGModule / DGSubmodule -- Quotient DG module: M / S
***************************************************

  * Operator: / (Macaulay2Doc),
  * Usage:
        Q = M / S
  * Inputs:
      * M, an instance of the type DGModule,
      * S, an instance of the type DGSubmodule, With
        S.ambient === M.
  * Outputs:
      * Q, an instance of the type DGQuotientModule,

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

Shorthand for dgQuotientModule(M, S).  See dgQuotientModule,
for semantics and invariants.

+------------------------------------+
|i1 : R = ZZ/101[x]                  |
|                                    |
|o1 = R                              |
|                                    |
|o1 : PolynomialRing                 |
+------------------------------------+
|i2 : A = koszulComplexDGA R         |
|                                    |
|o2 = {Ring => R                    }|
|      Underlying algebra => R[T   ] |
|                               1,1  |
|      Differential => {x}           |
|                                    |
|o2 : DGAlgebra                      |
+------------------------------------+
|i3 : M = freeDGModule(A, {0})       |
|                                    |
|o3 = {Base ring => R               }|
|      DG algebra => R[T   ]         |
|                       1,1          |
|                                 1  |
|      Natural module => (R[T   ])   |
|                            1,1     |
|      Generator degrees => {{0, 0}} |
|      Differentials on gens => {0}  |
|                                    |
|o3 : DGModule                       |
+------------------------------------+
|i4 : Z = dgSubmodule(M, {})         |
|                                    |
|o4 = DGSubmodule of ambient DGModule|
|     Degrees  => {}                 |
|     natural  => 0                  |
|     inclusion => 0                 |
|                                    |
|o4 : DGSubmodule                    |
+------------------------------------+
|i5 : Q = M / Z                      |
|                                    |
|o5 = DGQuotientModule Q = M / S     |
|                          1         |
|     Q.natural = (R[T   ])          |
|                     1,1            |
|     Degrees   = {{0, 0}}           |
|                                    |
|o5 : DGQuotientModule               |
+------------------------------------+
|i6 : ambient Q === M                |
|                                    |
|o6 = true                           |
+------------------------------------+
|i7 : isWellDefined Q                |
|                                    |
|o7 = true                           |
+------------------------------------+

The zero and top-dimensional boundary cases are handled consistently: M / 0 is
a DGQuotientModule wrapping a cokernel isomorphic to M, and M / M is the zero
DGQuotientModule.

+-------------------------------------------+
|i8 : Sfull = dgSubmodule(M, id_(M.natural))|
|                                           |
|o8 = DGSubmodule of ambient DGModule       |
|     Degrees  => {{0, 0}}                  |
|                          1                |
|     natural  => (R[T   ])                 |
|                     1,1                   |
|     inclusion => | 1 |                    |
|                                           |
|o8 : DGSubmodule                           |
+-------------------------------------------+
|i9 : isZero (M / Sfull)                    |
|                                           |
|o9 = true                                  |
+-------------------------------------------+

See also
========

  * Building DG modules, submodules, and quotients
    -- The DGModule / DGSubmodule /
    DGQuotientModule hierarchy and its constructors
  * dgQuotientModule -- Construct the quotient DG
    module M / S
  * DGQuotientModule -- The class of quotient DG
    modules M / S

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

  * DGModule / DGSubmodule -- Quotient DG
    module: M / S
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3287:0.

Module-like operations on DG modules -- Basic queries (generators, rank, degrees, homogeneity) extended to DG modules and their sub- and quotient modules
*********************************************************************************************************************************************************

Every DGModule, (and its DGSubmodule, /
see DGQuotientModule, variants) carries an underlying
graded A.natural-module, accessible via M.natural.  The standard Module (Macaulay2Doc),
methods — see numgens (Macaulay2Doc),
rank (Macaulay2Doc), degrees (Macaulay2Doc),
isHomogeneous (Macaulay2Doc), super (Macaulay2Doc),
cover (Macaulay2Doc), relations (Macaulay2Doc), —
are lifted directly onto the DG types, so code written against ordinary modules
can often be reused on DG objects unchanged.

Two DG-specific predicates are added:

isFreeDGModule, — is the underlying M.natural a free
graded A.natural-module?  Every DGModule built via freeDGModule,
satisfies this; user-built DGModules with non-free .natural slots
are tolerated by isWellDefined (Macaulay2Doc), as long as
the differential closes.

See isZero, — does the DG object have zero natural
generators? Consistent across DGModule, DGSubmodule, DGQuotientModule, and
DGIdeal, so predicates can be written generically.

+----------------------------------------------------+
|i1 : R = ZZ/101[x, y]                               |
|                                                    |
|o1 = R                                              |
|                                                    |
|o1 : PolynomialRing                                 |
+----------------------------------------------------+
|i2 : A = koszulComplexDGA R                         |
|                                                    |
|o2 = {Ring => R                          }          |
|      Underlying algebra => R[T   ..T   ]           |
|                               1,1   1,2            |
|      Differential => {x, y}                        |
|                                                    |
|o2 : DGAlgebra                                      |
+----------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1, 2})                 |
|                                                    |
|o3 = {Base ring => R                               }|
|      DG algebra => R[T   ..T   ]                   |
|                       1,1   1,2                    |
|                                       3            |
|      Natural module => (R[T   ..T   ])             |
|                            1,1   1,2               |
|      Generator degrees => {{0, 0}, {1, 0}, {2, 0}} |
|      Differentials on gens => {0, 0, 0}            |
|                                                    |
|o3 : DGModule                                       |
+----------------------------------------------------+
|i4 : numgens M                                      |
|                                                    |
|o4 = 3                                              |
+----------------------------------------------------+
|i5 : rank M                                         |
|                                                    |
|o5 = 3                                              |
+----------------------------------------------------+
|i6 : degrees M                                      |
|                                                    |
|o6 = {{0, 0}, {1, 0}, {2, 0}}                       |
|                                                    |
|o6 : List                                           |
+----------------------------------------------------+
|i7 : isHomogeneous M                                |
|                                                    |
|o7 = true                                           |
+----------------------------------------------------+
|i8 : isFreeDGModule M                               |
|                                                    |
|o8 = true                                           |
+----------------------------------------------------+
|i9 : isZero M                                       |
|                                                    |
|o9 = false                                          |
+----------------------------------------------------+

On quotient DG modules, super and cover both return the ambient DGModule, and
relations returns the matrix of the killed inclusion — mirroring M2's cokernel
encoding of a quotient.

+------------------------------------------------------+
|i10 : Anat = A.natural                                |
|                                                      |
|o10 = Anat                                            |
|                                                      |
|o10 : PolynomialRing, 2 skew commutative variable(s)  |
+------------------------------------------------------+
|i11 : Mone = freeDGModule(A, {0})                     |
|                                                      |
|o11 = {Base ring => R               }                 |
|       DG algebra => Anat                             |
|                             1                        |
|       Natural module => Anat                         |
|       Generator degrees => {{0, 0}}                  |
|       Differentials on gens => {0}                   |
|                                                      |
|o11 : DGModule                                        |
+------------------------------------------------------+
|i12 : S = dgSubmodule(Mone, matrix {{x_Anat, y_Anat}})|
|                                                      |
|o12 = DGSubmodule of ambient DGModule                 |
|      Degrees  => {{0, 1}, {0, 1}}                    |
|                      2                               |
|      natural  => Anat                                |
|      inclusion => | x y |                            |
|                                                      |
|o12 : DGSubmodule                                     |
+------------------------------------------------------+
|i13 : Q = Mone / S                                    |
|                                                      |
|o13 = DGQuotientModule Q = M / S                      |
|      Q.natural = cokernel | x y |                    |
|      Degrees   = {{0, 0}}                            |
|                                                      |
|o13 : DGQuotientModule                                |
+------------------------------------------------------+
|i14 : super Q === Mone                                |
|                                                      |
|o14 = true                                            |
+------------------------------------------------------+
|i15 : cover Q === Mone                                |
|                                                      |
|o15 = true                                            |
+------------------------------------------------------+
|i16 : relations Q                                     |
|                                                      |
|o16 = | x y |                                         |
|                                                      |
|                 1         2                          |
|o16 : Matrix Anat  <-- Anat                           |
+------------------------------------------------------+

See also
========

  * Operations on DG Submodules -- Sum,
    intersection, equality, and containment of DG submodules
  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * DGModule -- The class of DG modules over a DG algebra

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3405:0.

numgens(DGModule) -- Number of natural generators of a DG module (or sub- or quotient module)
*********************************************************************************************

  * Function: numgens (Macaulay2Doc),
  * Usage:
        n = numgens M
  * Inputs:
      * M, an instance of the type DGModule, A DGModule,
        DGSubmodule, or DGQuotientModule.
  * Outputs:
      * n, an integer (Macaulay2Doc), The number of natural
        generators of the underlying graded A.natural-module, equal to the
        length of its list of degrees.

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

+----------------------------------------------------+
|i1 : R = ZZ/101[x, y]                               |
|                                                    |
|o1 = R                                              |
|                                                    |
|o1 : PolynomialRing                                 |
+----------------------------------------------------+
|i2 : A = koszulComplexDGA R                         |
|                                                    |
|o2 = {Ring => R                          }          |
|      Underlying algebra => R[T   ..T   ]           |
|                               1,1   1,2            |
|      Differential => {x, y}                        |
|                                                    |
|o2 : DGAlgebra                                      |
+----------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1, 2})                 |
|                                                    |
|o3 = {Base ring => R                               }|
|      DG algebra => R[T   ..T   ]                   |
|                       1,1   1,2                    |
|                                       3            |
|      Natural module => (R[T   ..T   ])             |
|                            1,1   1,2               |
|      Generator degrees => {{0, 0}, {1, 0}, {2, 0}} |
|      Differentials on gens => {0, 0, 0}            |
|                                                    |
|o3 : DGModule                                       |
+----------------------------------------------------+
|i4 : numgens M == 3                                 |
|                                                    |
|o4 = true                                           |
+----------------------------------------------------+

For a DGSubmodule the count is the number of columns of the inclusion matrix (=
number of generators being included).  For a DGQuotientModule it is the number
of natural generators of the quotient presentation, which by construction
equals numgens (cover Q).natural.

+---------------------------------------------------+
|i5 : Anat = A.natural                              |
|                                                   |
|o5 = Anat                                          |
|                                                   |
|o5 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i6 : M1 = freeDGModule(A, {0})                     |
|                                                   |
|o6 = {Base ring => R               }               |
|      DG algebra => Anat                           |
|                            1                      |
|      Natural module => Anat                       |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o6 : DGModule                                      |
+---------------------------------------------------+
|i7 : S = dgSubmodule(M1, matrix {{x_Anat, y_Anat}})|
|                                                   |
|o7 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}, {0, 1}}                  |
|                     2                             |
|     natural  => Anat                              |
|     inclusion => | x y |                          |
|                                                   |
|o7 : DGSubmodule                                   |
+---------------------------------------------------+
|i8 : numgens S == 2                                |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+
|i9 : Q = M1 / S                                    |
|                                                   |
|o9 = DGQuotientModule Q = M / S                    |
|     Q.natural = cokernel | x y |                  |
|     Degrees   = {{0, 0}}                          |
|                                                   |
|o9 : DGQuotientModule                              |
+---------------------------------------------------+
|i10 : numgens Q == numgens M1                      |
|                                                   |
|o10 = true                                         |
+---------------------------------------------------+

Boundary case: a DGModule freely generated on an empty list has zero generators
and is isZero.

+-----------------------------------+
|i11 : M0 = freeDGModule(A, {})     |
|                                   |
|o11 = {Base ring => R             }|
|       DG algebra => Anat          |
|       Natural module => 0         |
|       Generator degrees => {}     |
|       Differentials on gens => {} |
|                                   |
|o11 : DGModule                     |
+-----------------------------------+
|i12 : numgens M0 == 0              |
|                                   |
|o12 = true                         |
+-----------------------------------+
|i13 : isZero M0                    |
|                                   |
|o13 = true                         |
+-----------------------------------+

See also
========

  * Module-like operations on DG modules
    -- Basic queries (generators, rank, degrees, homogeneity) extended
    to DG modules and their sub- and quotient modules
  * rank(DGModule) -- Rank of the underlying free
    A.natural-module
  * degrees(DGModule) -- Multi-degrees of the
    natural generators of a DG module
  * isZero -- Does the DG object have no natural
    generators?

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

  * numgens(DGModule) -- Number of natural
    generators of a DG module (or sub- or quotient module)
  * "numgens(DGQuotientModule)"
  * "numgens(DGSubmodule)"
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3453:0.

rank(DGModule) -- Rank of the underlying free A.natural-module
**************************************************************

  * Function: rank (Macaulay2Doc),
  * Usage:
        r = rank M
  * Inputs:
      * M, an instance of the type DGModule, A DGModule or
        DGSubmodule whose .natural is free.
  * Outputs:
      * r, an integer (Macaulay2Doc), rank M.natural.

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

For a free DGModule, rank and numgens (Macaulay2Doc), coincide.
For a DGSubmodule, rank reports the rank of the included free module (which is
numgens S when the inclusion is injective on natural generators — always the
case for submodules built by dgSubmodule).

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                   |
|                                                   |
|o3 = {Base ring => R                       }       |
|      DG algebra => R[T   ..T   ]                  |
|                       1,1   1,2                   |
|                                       2           |
|      Natural module => (R[T   ..T   ])            |
|                            1,1   1,2              |
|      Generator degrees => {{0, 0}, {1, 0}}        |
|      Differentials on gens => {0, 0}              |
|                                                   |
|o3 : DGModule                                      |
+---------------------------------------------------+
|i4 : rank M == numgens M                           |
|                                                   |
|o4 = true                                          |
+---------------------------------------------------+
|i5 : Anat = A.natural                              |
|                                                   |
|o5 = Anat                                          |
|                                                   |
|o5 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i6 : M1 = freeDGModule(A, {0})                     |
|                                                   |
|o6 = {Base ring => R               }               |
|      DG algebra => Anat                           |
|                            1                      |
|      Natural module => Anat                       |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o6 : DGModule                                      |
+---------------------------------------------------+
|i7 : S = dgSubmodule(M1, matrix {{x_Anat, y_Anat}})|
|                                                   |
|o7 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}, {0, 1}}                  |
|                     2                             |
|     natural  => Anat                              |
|     inclusion => | x y |                          |
|                                                   |
|o7 : DGSubmodule                                   |
+---------------------------------------------------+
|i8 : rank S                                        |
|                                                   |
|o8 = 2                                             |
+---------------------------------------------------+

After pruning a DGSubmodule with redundant inclusions, rank equals numgens on
the pruned object.

+--------------------------------------------------------------+
|i9 : Sbig = dgSubmodule(M1, matrix {{1_Anat, x_Anat, y_Anat}})|
|                                                              |
|o9 = DGSubmodule of ambient DGModule                          |
|     Degrees  => {{0, 0}, {0, 1}, {0, 1}}                     |
|                     3                                        |
|     natural  => Anat                                         |
|     inclusion => | 1 x y |                                   |
|                                                              |
|o9 : DGSubmodule                                              |
+--------------------------------------------------------------+
|i10 : Sp = prune Sbig                                         |
|                                                              |
|o10 = DGSubmodule of ambient DGModule                         |
|      Degrees  => {{0, 0}}                                    |
|                      1                                       |
|      natural  => Anat                                        |
|      inclusion => | 1 |                                      |
|                                                              |
|o10 : DGSubmodule                                             |
+--------------------------------------------------------------+
|i11 : numgens Sp == rank Sp                                   |
|                                                              |
|o11 = true                                                    |
+--------------------------------------------------------------+

Caveat
======

rank is not defined on DGQuotientModule,: the rank of a
cokernel module triggers codim computations that fail over non-affine graded
ambients.  Use numgens (Macaulay2Doc), for the generator count.

See also
========

  * Module-like operations on DG modules
    -- Basic queries (generators, rank, degrees, homogeneity) extended
    to DG modules and their sub- and quotient modules
  * numgens(DGModule) -- Number of natural
    generators of a DG module (or sub- or quotient module)

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

  * rank(DGModule) -- Rank of the underlying free
    A.natural-module
  * "rank(DGSubmodule)"
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3499:0.

degrees(DGModule) -- Multi-degrees of the natural generators of a DG module
***************************************************************************

  * Function: degrees (Macaulay2Doc),
  * Usage:
        ds = degrees M
  * Inputs:
      * M, an instance of the type DGModule, A DGModule,
        DGSubmodule, or DGQuotientModule.
  * Outputs:
      * ds, a list (Macaulay2Doc), A list of multi-degrees, one per
        natural generator.  Each multi-degree is a list whose first entry is
        the homological degree and whose remaining entries are the internal
        degrees.

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

+----------------------------------------------------+
|i1 : R = ZZ/101[x, y]                               |
|                                                    |
|o1 = R                                              |
|                                                    |
|o1 : PolynomialRing                                 |
+----------------------------------------------------+
|i2 : A = koszulComplexDGA R                         |
|                                                    |
|o2 = {Ring => R                          }          |
|      Underlying algebra => R[T   ..T   ]           |
|                               1,1   1,2            |
|      Differential => {x, y}                        |
|                                                    |
|o2 : DGAlgebra                                      |
+----------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1, 2})                 |
|                                                    |
|o3 = {Base ring => R                               }|
|      DG algebra => R[T   ..T   ]                   |
|                       1,1   1,2                    |
|                                       3            |
|      Natural module => (R[T   ..T   ])             |
|                            1,1   1,2               |
|      Generator degrees => {{0, 0}, {1, 0}, {2, 0}} |
|      Differentials on gens => {0, 0, 0}            |
|                                                    |
|o3 : DGModule                                       |
+----------------------------------------------------+
|i4 : degrees M == {{0,0},{1,0},{2,0}}               |
|                                                    |
|o4 = true                                           |
+----------------------------------------------------+

Internal degrees come from the ambient ring's grading and are concatenated onto
the homological degree.

+--------------------------------------------------+
|i5 : Rg = ZZ/101[x, y, Degrees => {{1,0}, {0,1}}] |
|                                                  |
|o5 = Rg                                           |
|                                                  |
|o5 : PolynomialRing                               |
+--------------------------------------------------+
|i6 : Ag = koszulComplexDGA Rg                     |
|                                                  |
|o6 = {Ring => Rg                          }       |
|      Underlying algebra => Rg[T   ..T   ]        |
|                                1,1   1,2         |
|      Differential => {x, y}                      |
|                                                  |
|o6 : DGAlgebra                                    |
+--------------------------------------------------+
|i7 : Mg = freeDGModule(Ag, {{0,0,0}, {1,0,0}})    |
|                                                  |
|o7 = {Base ring => Rg                            }|
|      DG algebra => Rg[T   ..T   ]                |
|                        1,1   1,2                 |
|                                        2         |
|      Natural module => (Rg[T   ..T   ])          |
|                             1,1   1,2            |
|      Generator degrees => {{0, 0, 0}, {1, 0, 0}} |
|      Differentials on gens => {0, 0}             |
|                                                  |
|o7 : DGModule                                     |
+--------------------------------------------------+
|i8 : degrees Mg                                   |
|                                                  |
|o8 = {{0, 0, 0}, {1, 0, 0}}                       |
|                                                  |
|o8 : List                                         |
+--------------------------------------------------+

See also
========

  * Module-like operations on DG modules
    -- Basic queries (generators, rank, degrees, homogeneity) extended
    to DG modules and their sub- and quotient modules
  * numgens(DGModule) -- Number of natural
    generators of a DG module (or sub- or quotient module)
  * isHomogeneous(DGModule) -- Test whether
    the underlying graded module is homogeneous

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

  * degrees(DGModule) -- Multi-degrees of the
    natural generators of a DG module
  * "degrees(DGQuotientModule)"
  * "degrees(DGSubmodule)"
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3536:0.

isHomogeneous(DGModule) -- Test whether the underlying graded module is homogeneous
***********************************************************************************

  * Function: isHomogeneous (Macaulay2Doc),
  * Usage:
        b = isHomogeneous M
  * Inputs:
      * M, an instance of the type DGModule, A DGModule,
        DGSubmodule, or DGQuotientModule.
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), isHomogeneous
        M.natural.

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

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 2})                   |
|                                                   |
|o3 = {Base ring => R                       }       |
|      DG algebra => R[T   ..T   ]                  |
|                       1,1   1,2                   |
|                                       2           |
|      Natural module => (R[T   ..T   ])            |
|                            1,1   1,2              |
|      Generator degrees => {{0, 0}, {2, 0}}        |
|      Differentials on gens => {0, 0}              |
|                                                   |
|o3 : DGModule                                      |
+---------------------------------------------------+
|i4 : isHomogeneous M                               |
|                                                   |
|o4 = true                                          |
+---------------------------------------------------+
|i5 : Anat = A.natural                              |
|                                                   |
|o5 = Anat                                          |
|                                                   |
|o5 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i6 : M1 = freeDGModule(A, {0})                     |
|                                                   |
|o6 = {Base ring => R               }               |
|      DG algebra => Anat                           |
|                            1                      |
|      Natural module => Anat                       |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o6 : DGModule                                      |
+---------------------------------------------------+
|i7 : S = dgSubmodule(M1, matrix {{x_Anat, y_Anat}})|
|                                                   |
|o7 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}, {0, 1}}                  |
|                     2                             |
|     natural  => Anat                              |
|     inclusion => | x y |                          |
|                                                   |
|o7 : DGSubmodule                                   |
+---------------------------------------------------+
|i8 : isHomogeneous S                               |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+
|i9 : Q = M1 / S                                    |
|                                                   |
|o9 = DGQuotientModule Q = M / S                    |
|     Q.natural = cokernel | x y |                  |
|     Degrees   = {{0, 0}}                          |
|                                                   |
|o9 : DGQuotientModule                              |
+---------------------------------------------------+
|i10 : isHomogeneous Q                              |
|                                                   |
|o10 = true                                         |
+---------------------------------------------------+

See also
========

  * Module-like operations on DG modules
    -- Basic queries (generators, rank, degrees, homogeneity) extended
    to DG modules and their sub- and quotient modules
  * degrees(DGModule) -- Multi-degrees of the
    natural generators of a DG module

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

  * isHomogeneous(DGModule) -- Test whether
    the underlying graded module is homogeneous
  * "isHomogeneous(DGQuotientModule)"
  * "isHomogeneous(DGSubmodule)"
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3568:0.

isFreeDGModule -- Is the underlying A.natural-module free?
**********************************************************

  * Usage:
        b = isFreeDGModule M
  * Inputs:
      * M, A DGModule or DGSubmodule.
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), isFreeModule
        M.natural.

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

Every DGModule built via freeDGModule, (and every
DGSubmodule of one) has free .natural, so this returns true in the typical
case.  The check exists because it is possible to build a DGModule directly
whose underlying .natural module is non-free, and isWellDefined (Macaulay2Doc),
will tolerate such an object as long as the
differential closes.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 2})                   |
|                                                   |
|o3 = {Base ring => R                       }       |
|      DG algebra => R[T   ..T   ]                  |
|                       1,1   1,2                   |
|                                       2           |
|      Natural module => (R[T   ..T   ])            |
|                            1,1   1,2              |
|      Generator degrees => {{0, 0}, {2, 0}}        |
|      Differentials on gens => {0, 0}              |
|                                                   |
|o3 : DGModule                                      |
+---------------------------------------------------+
|i4 : isFreeDGModule M                              |
|                                                   |
|o4 = true                                          |
+---------------------------------------------------+
|i5 : Anat = A.natural                              |
|                                                   |
|o5 = Anat                                          |
|                                                   |
|o5 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i6 : M1 = freeDGModule(A, {0})                     |
|                                                   |
|o6 = {Base ring => R               }               |
|      DG algebra => Anat                           |
|                            1                      |
|      Natural module => Anat                       |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o6 : DGModule                                      |
+---------------------------------------------------+
|i7 : S = dgSubmodule(M1, matrix {{x_Anat}})        |
|                                                   |
|o7 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => | x |                            |
|                                                   |
|o7 : DGSubmodule                                   |
+---------------------------------------------------+
|i8 : isFreeDGModule S                              |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+

Tensor products, base changes, and direct sums constructed by this package all
land in the free case, so isFreeDGModule remains true after any of those
operations.

+-----------------------------------------------------------------------------+
|i9 : MNK = (M ** R^2) ** R^2                                                 |
|                                                                             |
|o9 = {Base ring => R                                                         |
|      DG algebra => Anat                                                     |
|                            8                                                |
|      Natural module => Anat                                                 |
|      Generator degrees => {{0, 0}, {0, 0}, {0, 0}, {0, 0}, {2, 0}, {2, 0},  |
|      Differentials on gens => {0, 0, 0, 0, 0, 0, 0, 0}                      |
|                                                                             |
|o9 : DGModule                                                                |
|-----------------------------------------------------------------------------|
|               }                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|{2, 0}, {2, 0}}                                                              |
+-----------------------------------------------------------------------------+
|i10 : isFreeDGModule MNK                                                     |
|                                                                             |
|o10 = true                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * Module-like operations on DG modules
    -- Basic queries (generators, rank, degrees, homogeneity) extended
    to DG modules and their sub- and quotient modules
  * freeDGModule -- Construct a free DG module over a DG
    algebra
  * isWellDefined(DGModule) -- Check that a
    DG module has correct structure and that its differential squares to zero

Ways to use isFreeDGModule:
===========================

  * "isFreeDGModule(DGModule)"
  * "isFreeDGModule(DGSubmodule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3612:0.

isZero(DGModule) -- Does the DG object have no natural generators?
******************************************************************

  * Function: isZero,
  * Usage:
        b = isZero X
  * Inputs:
      * X, an instance of the type DGModule, A DGModule,
        DGSubmodule, DGQuotientModule, or DGIdeal.
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), True iff the natural
        presentation is zero.  Concretely: numgens M.natural == 0 for a
        DGModule, no inclusion columns (or a zero inclusion matrix) for a
        DGSubmodule, and Q.natural == 0 for a DGQuotientModule.  For a DGIdeal,
        see isZero(DGIdeal).

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

+------------------------------------+
|i1 : R = ZZ/101[x]                  |
|                                    |
|o1 = R                              |
|                                    |
|o1 : PolynomialRing                 |
+------------------------------------+
|i2 : A = koszulComplexDGA R         |
|                                    |
|o2 = {Ring => R                    }|
|      Underlying algebra => R[T   ] |
|                               1,1  |
|      Differential => {x}           |
|                                    |
|o2 : DGAlgebra                      |
+------------------------------------+
|i3 : M0 = freeDGModule(A, {})       |
|                                    |
|o3 = {Base ring => R             }  |
|      DG algebra => R[T   ]         |
|                       1,1          |
|      Natural module => 0           |
|      Generator degrees => {}       |
|      Differentials on gens => {}   |
|                                    |
|o3 : DGModule                       |
+------------------------------------+
|i4 : isZero M0                      |
|                                    |
|o4 = true                           |
+------------------------------------+
|i5 : M = freeDGModule(A, {0})       |
|                                    |
|o5 = {Base ring => R               }|
|      DG algebra => R[T   ]         |
|                       1,1          |
|                                 1  |
|      Natural module => (R[T   ])   |
|                            1,1     |
|      Generator degrees => {{0, 0}} |
|      Differentials on gens => {0}  |
|                                    |
|o5 : DGModule                       |
+------------------------------------+
|i6 : not isZero M                   |
|                                    |
|o6 = true                           |
+------------------------------------+

A zero DGSubmodule can be built explicitly via a zero inclusion matrix.

+----------------------------------------------------+
|i7 : Anat = A.natural                               |
|                                                    |
|o7 = Anat                                           |
|                                                    |
|o7 : PolynomialRing, 1 skew commutative variable(s) |
+----------------------------------------------------+
|i8 : Z = dgSubmodule(M, map(M.natural, (Anat)^0, 0))|
|                                                    |
|o8 = DGSubmodule of ambient DGModule                |
|     Degrees  => {}                                 |
|     natural  => 0                                  |
|     inclusion => 0                                 |
|                                                    |
|o8 : DGSubmodule                                    |
+----------------------------------------------------+
|i9 : isZero Z                                       |
|                                                    |
|o9 = true                                           |
+----------------------------------------------------+

Quotienting a DGModule by its whole ambient yields a zero DGQuotientModule.

+-------------------------------------------+
|i10 : Full = dgSubmodule(M, id_(M.natural))|
|                                           |
|o10 = DGSubmodule of ambient DGModule      |
|      Degrees  => {{0, 0}}                 |
|                      1                    |
|      natural  => Anat                     |
|      inclusion => | 1 |                   |
|                                           |
|o10 : DGSubmodule                          |
+-------------------------------------------+
|i11 : Q = M / Full                         |
|                                           |
|o11 = DGQuotientModule Q = M / S           |
|      Q.natural = cokernel | 1 |           |
|      Degrees   = {{0, 0}}                 |
|                                           |
|o11 : DGQuotientModule                     |
+-------------------------------------------+
|i12 : isZero Q                             |
|                                           |
|o12 = true                                 |
+-------------------------------------------+

See also
========

  * Module-like operations on DG modules
    -- Basic queries (generators, rank, degrees, homogeneity) extended
    to DG modules and their sub- and quotient modules
  * numgens(DGModule) -- Number of natural
    generators of a DG module (or sub- or quotient module)
  * isZero(DGIdeal) -- Predicates on a DG
    ideal

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

  * isZero(DGModule) -- Does the DG object have no
    natural generators?
  * "isZero(DGQuotientModule)"
  * "isZero(DGSubmodule)"
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3659:0.

super(DGSubmodule) -- Ambient DGModule, cover, and relation matrix of a DG sub- or quotient module
**************************************************************************************************

  * Function: super (Macaulay2Doc),

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

These mirror the analogous M2 Module accessors.

super S (for a DGSubmodule S) and super Q, cover Q (for a DGQuotientModule Q)
all return the ambient DGModule M from which the sub- or quotient was built.

relations Q returns the inclusion matrix of the killed submodule, encoding the
cokernel presentation of Q.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : M = freeDGModule(A, {0})                      |
|                                                   |
|o3 = {Base ring => R                    }          |
|      DG algebra => R[T   ..T   ]                  |
|                       1,1   1,2                   |
|                                       1           |
|      Natural module => (R[T   ..T   ])            |
|                            1,1   1,2              |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o3 : DGModule                                      |
+---------------------------------------------------+
|i4 : Anat = A.natural                              |
|                                                   |
|o4 = Anat                                          |
|                                                   |
|o4 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i5 : S = dgSubmodule(M, matrix {{x_Anat, y_Anat}}) |
|                                                   |
|o5 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}, {0, 1}}                  |
|                     2                             |
|     natural  => Anat                              |
|     inclusion => | x y |                          |
|                                                   |
|o5 : DGSubmodule                                   |
+---------------------------------------------------+
|i6 : super S === M                                 |
|                                                   |
|o6 = true                                          |
+---------------------------------------------------+
|i7 : Q = M / S                                     |
|                                                   |
|o7 = DGQuotientModule Q = M / S                    |
|     Q.natural = cokernel | x y |                  |
|     Degrees   = {{0, 0}}                          |
|                                                   |
|o7 : DGQuotientModule                              |
+---------------------------------------------------+
|i8 : super Q === M                                 |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+
|i9 : cover Q === M                                 |
|                                                   |
|o9 = true                                          |
+---------------------------------------------------+
|i10 : numcols relations Q == 2                     |
|                                                   |
|o10 = true                                         |
+---------------------------------------------------+

See also
========

  * Module-like operations on DG modules
    -- Basic queries (generators, rank, degrees, homogeneity) extended
    to DG modules and their sub- and quotient modules
  * DGSubmodule -- The class of d-closed submodules of a DG
    module
  * DGQuotientModule -- The class of quotient DG
    modules M / S

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

  * "super(DGQuotientModule)"
  * super(DGSubmodule) -- Ambient DGModule,
    cover, and relation matrix of a DG sub- or quotient module
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3694:0.

Operations on DG Submodules -- Sum, intersection, equality, and containment of DG submodules
********************************************************************************************

DGSubmodules of a common ambient DGModule M form a lattice under sum,
intersection, and inclusion — each operation preserves d-closure by elementary
arguments paralleling the Operations on DG Ideals,
story:

Sum: d(s + t) = d(s) + d(t) \in S + T when s \in S and t \in T.

Intersection: if x \in S \cap T then d(x) \in S (by d-closure of S) and d(x)
\in T (by d-closure of T), so d(x) \in S \cap T.

Containment / equality: read off directly from the images of the inclusions in
M.natural.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : M = freeDGModule(A, {0})                      |
|                                                   |
|o3 = {Base ring => R                    }          |
|      DG algebra => R[T   ..T   ]                  |
|                       1,1   1,2                   |
|                                       1           |
|      Natural module => (R[T   ..T   ])            |
|                            1,1   1,2              |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o3 : DGModule                                      |
+---------------------------------------------------+
|i4 : Anat = A.natural                              |
|                                                   |
|o4 = Anat                                          |
|                                                   |
|o4 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i5 : S = dgSubmodule(M, matrix {{x_Anat}})         |
|                                                   |
|o5 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => | x |                            |
|                                                   |
|o5 : DGSubmodule                                   |
+---------------------------------------------------+
|i6 : T = dgSubmodule(M, matrix {{y_Anat}})         |
|                                                   |
|o6 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => | y |                            |
|                                                   |
|o6 : DGSubmodule                                   |
+---------------------------------------------------+
|i7 : ST = S + T                                    |
|                                                   |
|o7 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}, {0, 1}}                  |
|                     2                             |
|     natural  => Anat                              |
|     inclusion => | x y |                          |
|                                                   |
|o7 : DGSubmodule                                   |
+---------------------------------------------------+
|i8 : isWellDefined ST                              |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+
|i9 : isSubset(S, ST) and isSubset(T, ST)           |
|                                                   |
|o9 = true                                          |
+---------------------------------------------------+
|i10 : cap = intersect(S, T)                        |
|                                                   |
|o10 = DGSubmodule of ambient DGModule              |
|      Degrees  => {{0, 2}}                         |
|                      1                            |
|      natural  => Anat                             |
|      inclusion => | xy |                          |
|                                                   |
|o10 : DGSubmodule                                  |
+---------------------------------------------------+
|i11 : isWellDefined cap                            |
|                                                   |
|o11 = true                                         |
+---------------------------------------------------+
|i12 : isSubset(cap, S) and isSubset(cap, T)        |
|                                                   |
|o12 = true                                         |
+---------------------------------------------------+

Sum is idempotent (S + S == S) and intersecting with the zero submodule yields
the zero submodule.

+-----------------------------------------------------+
|i13 : (S + S) == S                                   |
|                                                     |
|o13 = true                                           |
+-----------------------------------------------------+
|i14 : Z = dgSubmodule(M, map(M.natural, (Anat)^0, 0))|
|                                                     |
|o14 = DGSubmodule of ambient DGModule                |
|      Degrees  => {}                                 |
|      natural  => 0                                  |
|      inclusion => 0                                 |
|                                                     |
|o14 : DGSubmodule                                    |
+-----------------------------------------------------+
|i15 : isZero intersect(S, Z)                         |
|                                                     |
|o15 = true                                           |
+-----------------------------------------------------+

All four operations require the DGSubmodules to share an ambient DGModule (via
=== — object identity, not just isomorphism), and raise an error otherwise.

See also
========

  * DGSubmodule -- The class of d-closed submodules of a DG
    module
  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * Module-like operations on DG modules
    -- Basic queries (generators, rank, degrees, homogeneity) extended
    to DG modules and their sub- and quotient modules

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3749:0.

DGSubmodule + DGSubmodule -- Sum of two DG submodules of a common ambient
*************************************************************************

  * Operator: + (Macaulay2Doc),
  * Usage:
        U = S + T
  * Inputs:
      * S, an instance of the type DGSubmodule,
      * T, an instance of the type DGSubmodule, With
        S.ambient === T.ambient.
  * Outputs:
      * U, an instance of the type DGSubmodule, The
        DGSubmodule of S.ambient whose inclusion matrix is the horizontal
        concatenation of S.inclusion.natural and T.inclusion.natural.

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

Preserves d-closure and contains both summands.  Idempotent: S + S == S.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : M = freeDGModule(A, {0})                      |
|                                                   |
|o3 = {Base ring => R                    }          |
|      DG algebra => R[T   ..T   ]                  |
|                       1,1   1,2                   |
|                                       1           |
|      Natural module => (R[T   ..T   ])            |
|                            1,1   1,2              |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o3 : DGModule                                      |
+---------------------------------------------------+
|i4 : Anat = A.natural                              |
|                                                   |
|o4 = Anat                                          |
|                                                   |
|o4 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i5 : S = dgSubmodule(M, matrix {{x_Anat}})         |
|                                                   |
|o5 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => | x |                            |
|                                                   |
|o5 : DGSubmodule                                   |
+---------------------------------------------------+
|i6 : T = dgSubmodule(M, matrix {{y_Anat}})         |
|                                                   |
|o6 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => | y |                            |
|                                                   |
|o6 : DGSubmodule                                   |
+---------------------------------------------------+
|i7 : ST = S + T                                    |
|                                                   |
|o7 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}, {0, 1}}                  |
|                     2                             |
|     natural  => Anat                              |
|     inclusion => | x y |                          |
|                                                   |
|o7 : DGSubmodule                                   |
+---------------------------------------------------+
|i8 : isWellDefined ST                              |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+
|i9 : isSubset(S, ST) and isSubset(T, ST)           |
|                                                   |
|o9 = true                                          |
+---------------------------------------------------+
|i10 : (S + S) == S                                 |
|                                                   |
|o10 = true                                         |
+---------------------------------------------------+

Caveat
======

If the two ambients are distinct objects (even if isomorphic), this raises an
error — the operation is about lattice structure within a fixed ambient.

See also
========

  * Operations on DG Submodules -- Sum,
    intersection, equality, and containment of DG submodules
  * intersect(DGSubmodule,DGSubmodule)
    -- Intersection of two DG
    submodules of a common ambient
  * isSubset(DGSubmodule,DGSubmodule), --
    Equality and containment of DG submodules

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

  * DGSubmodule + DGSubmodule -- Sum of two
    DG submodules of a common ambient
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3790:0.

intersect(DGSubmodule,DGSubmodule) -- Intersection of two DG submodules of a common ambient
*******************************************************************************************

  * Function: intersect (Macaulay2Doc),
  * Usage:
        U = intersect(S, T)
  * Inputs:
      * S, an instance of the type DGSubmodule,
      * T, an instance of the type DGSubmodule, With
        S.ambient === T.ambient.
  * Outputs:
      * U, an instance of the type DGSubmodule, The
        DGSubmodule of S.ambient whose image is image(S.inclusion.natural) \cap
        image(T.inclusion.natural).

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

Preserves d-closure directly.  Intersecting with the zero submodule yields the
zero submodule; intersecting with the same submodule is idempotent
(intersect(S, S) == S as submodules).

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : M = freeDGModule(A, {0})                      |
|                                                   |
|o3 = {Base ring => R                    }          |
|      DG algebra => R[T   ..T   ]                  |
|                       1,1   1,2                   |
|                                       1           |
|      Natural module => (R[T   ..T   ])            |
|                            1,1   1,2              |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o3 : DGModule                                      |
+---------------------------------------------------+
|i4 : Anat = A.natural                              |
|                                                   |
|o4 = Anat                                          |
|                                                   |
|o4 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i5 : S = dgSubmodule(M, matrix {{x_Anat}})         |
|                                                   |
|o5 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => | x |                            |
|                                                   |
|o5 : DGSubmodule                                   |
+---------------------------------------------------+
|i6 : T = dgSubmodule(M, matrix {{x_Anat * y_Anat}})|
|                                                   |
|o6 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 2}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => | xy |                           |
|                                                   |
|o6 : DGSubmodule                                   |
+---------------------------------------------------+
|i7 : cap = intersect(S, T)                         |
|                                                   |
|o7 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 2}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => | xy |                           |
|                                                   |
|o7 : DGSubmodule                                   |
+---------------------------------------------------+
|i8 : isWellDefined cap                             |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+
|i9 : isSubset(cap, S) and isSubset(cap, T)         |
|                                                   |
|o9 = true                                          |
+---------------------------------------------------+

Boundary case: intersection with the zero submodule is zero.

+-----------------------------------------------------+
|i10 : Z = dgSubmodule(M, map(M.natural, (Anat)^0, 0))|
|                                                     |
|o10 = DGSubmodule of ambient DGModule                |
|      Degrees  => {}                                 |
|      natural  => 0                                  |
|      inclusion => 0                                 |
|                                                     |
|o10 : DGSubmodule                                    |
+-----------------------------------------------------+
|i11 : isZero intersect(S, Z)                         |
|                                                     |
|o11 = true                                           |
+-----------------------------------------------------+

See also
========

  * Operations on DG Submodules -- Sum,
    intersection, equality, and containment of DG submodules
  * DGSubmodule + DGSubmodule -- Sum of two
    DG submodules of a common ambient

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

  * intersect(DGSubmodule,DGSubmodule)
    -- Intersection of two DG
    submodules of a common ambient
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3830:0.

DGSubmodule == DGSubmodule -- Equality and containment of DG submodules
***********************************************************************

  * Operator: == (Macaulay2Doc),
  * Usage:
        b = S == T
        b = isSubset(S, T)
  * Inputs:
      * S, an instance of the type DGSubmodule,
      * T, an instance of the type DGSubmodule,
  * Outputs:
      * b, a Boolean value (Macaulay2Doc),

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

Equality requires the ambients to be the same object (===) and the images of
the inclusions to agree. Containment further requires the DGSubmodules share an
ambient and tests the image inclusions.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : M = freeDGModule(A, {0})                      |
|                                                   |
|o3 = {Base ring => R                    }          |
|      DG algebra => R[T   ..T   ]                  |
|                       1,1   1,2                   |
|                                       1           |
|      Natural module => (R[T   ..T   ])            |
|                            1,1   1,2              |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o3 : DGModule                                      |
+---------------------------------------------------+
|i4 : Anat = A.natural                              |
|                                                   |
|o4 = Anat                                          |
|                                                   |
|o4 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i5 : S = dgSubmodule(M, matrix {{x_Anat}})         |
|                                                   |
|o5 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => | x |                            |
|                                                   |
|o5 : DGSubmodule                                   |
+---------------------------------------------------+
|i6 : U = dgSubmodule(M, matrix {{x_Anat, y_Anat}}) |
|                                                   |
|o6 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}, {0, 1}}                  |
|                     2                             |
|     natural  => Anat                              |
|     inclusion => | x y |                          |
|                                                   |
|o6 : DGSubmodule                                   |
+---------------------------------------------------+
|i7 : isSubset(S, U)                                |
|                                                   |
|o7 = true                                          |
+---------------------------------------------------+
|i8 : not isSubset(U, S)                            |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+
|i9 : S == S                                        |
|                                                   |
|o9 = true                                          |
+---------------------------------------------------+

Two DGSubmodules built from distinct ambient DGModules are never equal, even if
the ambient modules are abstractly isomorphic.

+---------------------------------------------+
|i10 : M' = freeDGModule(A, {0})              |
|                                             |
|o10 = {Base ring => R               }        |
|       DG algebra => Anat                    |
|                             1               |
|       Natural module => Anat                |
|       Generator degrees => {{0, 0}}         |
|       Differentials on gens => {0}          |
|                                             |
|o10 : DGModule                               |
+---------------------------------------------+
|i11 : S' = dgSubmodule(M', matrix {{x_Anat}})|
|                                             |
|o11 = DGSubmodule of ambient DGModule        |
|      Degrees  => {{0, 1}}                   |
|                      1                      |
|      natural  => Anat                       |
|      inclusion => | x |                     |
|                                             |
|o11 : DGSubmodule                            |
+---------------------------------------------+
|i12 : not (S == S')                          |
|                                             |
|o12 = true                                   |
+---------------------------------------------+

See also
========

  * Operations on DG Submodules -- Sum,
    intersection, equality, and containment of DG submodules
  * DGSubmodule + DGSubmodule -- Sum of two
    DG submodules of a common ambient
  * intersect(DGSubmodule,DGSubmodule)
    -- Intersection of two DG
    submodules of a common ambient

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

  * DGSubmodule == DGSubmodule -- Equality
    and containment of DG submodules
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3873:0.

Image, kernel, and cokernel of DG module maps -- Building DG submodules and DG quotient modules from a DG module map
********************************************************************************************************************

For a DG module map f : M -> N of DG modules over a common DG algebra A, the
package provides three chain-level constructions:

image(DGModuleMap), — the image of f, built as a
DGSubmodule, of the target N.  A chain map sends cycles to
cycles and boundaries to boundaries, so the column span of f.natural is
automatically d-closed in N.natural; no d-saturation is needed.

See kernel(DGModuleMap), — the kernel of f, built as
a DGSubmodule, of the source M.  Again chain-map-ness gives
d-closure for free.

See cokernel(DGModuleMap), — the cokernel of f,
built as a DGQuotientModule, equal to target f / image
f.

These three operations fit together in the usual short exact sequence: for any
f, we have rank(source f) == numgens(kernel f) + numgens(image f) and
rank(target f) == numgens(image f) + numgens(cokernel f) whenever the natural
modules are free.

A genuinely informative example: let R = k[x, y]/(x^2, y^2) and let KM =
koszulComplexDGM R^1 be its Koszul DG module. Multiplication by x is a degree-0
endomorphism of KM because x is central in the underlying ring:

+--------------------------------------------------+
|i1 : R = ZZ/101[x, y] / ideal(x^2, y^2)           |
|                                                  |
|o1 = R                                            |
|                                                  |
|o1 : QuotientRing                                 |
+--------------------------------------------------+
|i2 : A = koszulComplexDGA R                       |
|                                                  |
|o2 = {Ring => R                          }        |
|      Underlying algebra => R[T   ..T   ]         |
|                               1,1   1,2          |
|      Differential => {x, y}                      |
|                                                  |
|o2 : DGAlgebra                                    |
+--------------------------------------------------+
|i3 : KM = koszulComplexDGM R^1                    |
|                                                  |
|o3 = {Base ring => R                    }         |
|      DG algebra => R[T   ..T   ]                 |
|                       1,1   1,2                  |
|                                       1          |
|      Natural module => (R[T   ..T   ])           |
|                            1,1   1,2             |
|      Generator degrees => {{0, 0}}               |
|      Differentials on gens => {0}                |
|                                                  |
|o3 : DGModule                                     |
+--------------------------------------------------+
|i4 : mx = dgModuleMap(KM, KM, x * id_(KM.natural))|
|                                                  |
|                               1                  |
|o4 = {Source => (R[T   ..T   ]) }                 |
|                    1,1   1,2                     |
|                               1                  |
|      Target => (R[T   ..T   ])                   |
|                    1,1   1,2                     |
|      Natural => | x |                            |
|                                                  |
|o4 : DGModuleMap                                  |
+--------------------------------------------------+
|i5 : isWellDefined mx                             |
|                                                  |
|o5 = true                                         |
+--------------------------------------------------+

Since x^2 = 0 in R, the composition mx o mx is the zero map, which chain-level
is the statement image mx \subseteq kernel mx.  The three constructions expose
this directly:

+----------------------------------------------+
|i6 : imgMx = image mx;                        |
+----------------------------------------------+
|i7 : kerMx = kernel mx;                       |
+----------------------------------------------+
|i8 : cokMx = cokernel mx;                     |
+----------------------------------------------+
|i9 : all({imgMx, kerMx, cokMx}, isWellDefined)|
|                                              |
|o9 = true                                     |
+----------------------------------------------+
|i10 : numcols (inclusion imgMx).natural       |
|                                              |
|o10 = 1                                       |
+----------------------------------------------+
|i11 : numcols (inclusion kerMx).natural       |
|                                              |
|o11 = 1                                       |
+----------------------------------------------+
|i12 : isSubset(imgMx, kerMx)                  |
|                                              |
|o12 = true                                    |
+----------------------------------------------+

The cokernel is the quotient DG module KM / x \cdot KM; at the natural level it
is KM \otimes_R R/(x) = k[y]/(y^2) \otimes_k \Lambda(T_1, T_2), presented by
the 1 x 1 matrix [x] per generator:

+--------------------------------------------------+
|i13 : presentation cokMx.natural                  |
|                                                  |
|o13 = | x |                                       |
|                                                  |
|                            1                    1|
|o13 : Matrix (R[T   ..T   ])  <-- (R[T   ..T   ]) |
|                 1,1   1,2            1,1   1,2   |
+--------------------------------------------------+

The three operations are used throughout the package -- notably by
homology at degree n, which computes
kernel(d_n) / image(d_{n+1}) via these primitives.

Finally, each of image mx, kernel mx, cokernel mx is itself a DG module, so
toComplex(DGModule), (or its DGSubmodule,
/ see DGQuotientModule, variants) converts
them into ordinary chain complexes one can hand to Complexes.
For the cokernel in particular, the underlying complex is KM
/ x \cdot KM and its homology picks up the classes that become new cycles when
the x-direction is killed:

+--------------------------------------------------------------------+
|i14 : CcokMx = toComplex cokMx                                      |
|                                                                    |
|o14 = cokernel | x | <-- cokernel {1} | x 0 | <-- cokernel {2} | x ||
|                                  {1} | 0 x |                       |
|      0                                           2                 |
|                         1                                          |
|                                                                    |
|o14 : Complex                                                       |
+--------------------------------------------------------------------+
|i15 : apply(0..(maxDegree cokMx), n -> prune HH_n CcokMx)           |
|                                                                    |
|o15 = (cokernel | y x |, cokernel | y x 0 0 |, cokernel | y x |)    |
|                                  | 0 0 y x |                       |
|                                                                    |
|o15 : Sequence                                                      |
+--------------------------------------------------------------------+

See also
========

  * DGModuleMap -- The class of morphisms of DG modules
    over a common DG algebra
  * Building DG modules, submodules, and quotients
    -- The DGModule / DGSubmodule /
    DGQuotientModule hierarchy and its constructors
  * Basic operations on DG Module Maps
    -- Outlines some basic operations on DGModuleMaps

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3963:0.

image(DGModuleMap) -- Image of a DG module map as a DG submodule of its target
******************************************************************************

  * Function: image (Macaulay2Doc),
  * Usage:
        S = image f
  * Inputs:
      * f, an instance of the type DGModuleMap, A morphism
        M -> N of DG modules over a common DG algebra.
  * Outputs:
      * S, an instance of the type DGSubmodule, The DG
        submodule of N = target f whose column span in N.natural is the image
        of f.natural.  Zero columns of f.natural are dropped, so the number of
        generators of the result reflects the rank of the image rather than the
        width of the presentation.

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

Since f is a chain map, the column span of f.natural is already d-closed in
N.natural; see dgSubmodule, is called without a d-saturation
loop.

A substantive example: over R = k[x, y]/(x^2, y^2) take the Koszul DG module KM
= koszulComplexDGM R^1 and the endomorphism "multiplication by x."  Its image
is a proper DG submodule -- it cannot be all of KM because x annihilates the
class of 1 \in R modulo its own image (since x^2 = 0):

+------------------------------------------------------+
|i1 : R = ZZ/101[x, y] / ideal(x^2, y^2)               |
|                                                      |
|o1 = R                                                |
|                                                      |
|o1 : QuotientRing                                     |
+------------------------------------------------------+
|i2 : A = koszulComplexDGA R                           |
|                                                      |
|o2 = {Ring => R                          }            |
|      Underlying algebra => R[T   ..T   ]             |
|                               1,1   1,2              |
|      Differential => {x, y}                          |
|                                                      |
|o2 : DGAlgebra                                        |
+------------------------------------------------------+
|i3 : KM = koszulComplexDGM R^1                        |
|                                                      |
|o3 = {Base ring => R                    }             |
|      DG algebra => R[T   ..T   ]                     |
|                       1,1   1,2                      |
|                                       1              |
|      Natural module => (R[T   ..T   ])               |
|                            1,1   1,2                 |
|      Generator degrees => {{0, 0}}                   |
|      Differentials on gens => {0}                    |
|                                                      |
|o3 : DGModule                                         |
+------------------------------------------------------+
|i4 : mx = dgModuleMap(KM, KM, x * id_(KM.natural))    |
|                                                      |
|                               1                      |
|o4 = {Source => (R[T   ..T   ]) }                     |
|                    1,1   1,2                         |
|                               1                      |
|      Target => (R[T   ..T   ])                       |
|                    1,1   1,2                         |
|      Natural => | x |                                |
|                                                      |
|o4 : DGModuleMap                                      |
+------------------------------------------------------+
|i5 : imgMx = image mx                                 |
|                                                      |
|o5 = DGSubmodule of ambient DGModule                  |
|     Degrees  => {{0, 0}}                             |
|                                1                     |
|     natural  => (R[T   ..T   ])                      |
|                     1,1   1,2                        |
|     inclusion => | x |                               |
|                                                      |
|o5 : DGSubmodule                                      |
+------------------------------------------------------+
|i6 : isWellDefined imgMx                              |
|                                                      |
|o6 = true                                             |
+------------------------------------------------------+
|i7 : numcols (inclusion imgMx).natural                |
|                                                      |
|o7 = 1                                                |
+------------------------------------------------------+
|i8 : isSubset(imgMx, dgSubmodule(KM, id_(KM.natural)))|
|                                                      |
|o8 = true                                             |
+------------------------------------------------------+

The image of the inclusion of a DG submodule S \subset M recovers S itself:

+----------------------------------------------+
|i9 : Sfull = dgSubmodule(KM, id_(KM.natural));|
+----------------------------------------------+
|i10 : (image (inclusion Sfull)) == Sfull      |
|                                              |
|o10 = true                                    |
+----------------------------------------------+

See also
========

  * Image, kernel, and cokernel of DG module maps
    -- Building DG submodules and DG quotient
    modules from a DG module map
  * kernel(DGModuleMap) -- Kernel of a DG
    module map as a DG submodule of its source
  * cokernel(DGModuleMap) -- Cokernel of a DG
    module map as a DG quotient module of its target
  * DGSubmodule -- The class of d-closed submodules of a DG
    module

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

  * image(DGModuleMap) -- Image of a DG module
    map as a DG submodule of its target
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4015:0.

kernel(DGModuleMap) -- Kernel of a DG module map as a DG submodule of its source
********************************************************************************

  * Function: kernel (Macaulay2Doc),
  * Usage:
        S = kernel f
  * Inputs:
      * f, an instance of the type DGModuleMap, A morphism
        M -> N of DG modules over a common DG algebra.
  * Optional inputs (Macaulay2Doc),:
      * DegreeLimit (Macaulay2Doc),
        => ..., default value {},
      * Strategy (Macaulay2Doc),
        => ..., default value {},
      * SubringLimit (Macaulay2Doc),
        => ..., default value infinity,
  * Outputs:
      * S, an instance of the type DGSubmodule, The DG
        submodule of M = source f generated by the kernel of f.natural as a
        module over M.dgAlgebra.natural.

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

A chain map sends cycles to cycles, so the kernel of f.natural at the module
level is already d-closed.  The constructor takes the natural-level kernel
generators and wraps them with dgSubmodule.

Mathematically interesting example: over R = k[x, y]/(x^2, y^2) the
endomorphism "multiplication by x" of the Koszul DG module KM squares to zero,
so its kernel contains its image:

+--------------------------------------------------+
|i1 : R = ZZ/101[x, y] / ideal(x^2, y^2)           |
|                                                  |
|o1 = R                                            |
|                                                  |
|o1 : QuotientRing                                 |
+--------------------------------------------------+
|i2 : A = koszulComplexDGA R                       |
|                                                  |
|o2 = {Ring => R                          }        |
|      Underlying algebra => R[T   ..T   ]         |
|                               1,1   1,2          |
|      Differential => {x, y}                      |
|                                                  |
|o2 : DGAlgebra                                    |
+--------------------------------------------------+
|i3 : KM = koszulComplexDGM R^1                    |
|                                                  |
|o3 = {Base ring => R                    }         |
|      DG algebra => R[T   ..T   ]                 |
|                       1,1   1,2                  |
|                                       1          |
|      Natural module => (R[T   ..T   ])           |
|                            1,1   1,2             |
|      Generator degrees => {{0, 0}}               |
|      Differentials on gens => {0}                |
|                                                  |
|o3 : DGModule                                     |
+--------------------------------------------------+
|i4 : mx = dgModuleMap(KM, KM, x * id_(KM.natural))|
|                                                  |
|                               1                  |
|o4 = {Source => (R[T   ..T   ]) }                 |
|                    1,1   1,2                     |
|                               1                  |
|      Target => (R[T   ..T   ])                   |
|                    1,1   1,2                     |
|      Natural => | x |                            |
|                                                  |
|o4 : DGModuleMap                                  |
+--------------------------------------------------+
|i5 : kerMx = kernel mx                            |
|                                                  |
|o5 = DGSubmodule of ambient DGModule              |
|     Degrees  => {{0, 1}}                         |
|                                1                 |
|     natural  => (R[T   ..T   ])                  |
|                     1,1   1,2                    |
|     inclusion => | x |                           |
|                                                  |
|o5 : DGSubmodule                                  |
+--------------------------------------------------+
|i6 : imgMx = image mx                             |
|                                                  |
|o6 = DGSubmodule of ambient DGModule              |
|     Degrees  => {{0, 0}}                         |
|                                1                 |
|     natural  => (R[T   ..T   ])                  |
|                     1,1   1,2                    |
|     inclusion => | x |                           |
|                                                  |
|o6 : DGSubmodule                                  |
+--------------------------------------------------+
|i7 : isWellDefined kerMx                          |
|                                                  |
|o7 = true                                         |
+--------------------------------------------------+
|i8 : numcols (inclusion kerMx).natural            |
|                                                  |
|o8 = 1                                            |
+--------------------------------------------------+
|i9 : isSubset(imgMx, kerMx)                       |
|                                                  |
|o9 = true                                         |
+--------------------------------------------------+

The inclusion of a DG submodule is injective, so its kernel is zero:

+-----------------------------------------------+
|i10 : Sfull = dgSubmodule(KM, id_(KM.natural));|
+-----------------------------------------------+
|i11 : isZero kernel (inclusion Sfull)          |
|                                               |
|o11 = true                                     |
+-----------------------------------------------+

See also
========

  * Image, kernel, and cokernel of DG module maps
    -- Building DG submodules and DG quotient
    modules from a DG module map
  * image(DGModuleMap) -- Image of a DG module
    map as a DG submodule of its target
  * cokernel(DGModuleMap) -- Cokernel of a DG
    module map as a DG quotient module of its target
  * DGSubmodule -- The class of d-closed submodules of a DG
    module

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

  * kernel(DGModuleMap) -- Kernel of a DG
    module map as a DG submodule of its source
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4063:0.

cokernel(DGModuleMap) -- Cokernel of a DG module map as a DG quotient module of its target
******************************************************************************************

  * Function: cokernel (Macaulay2Doc),
  * Usage:
        Q = cokernel f
  * Inputs:
      * f, an instance of the type DGModuleMap, A morphism
        M -> N of DG modules over a common DG algebra.
  * Outputs:
      * Q, an instance of the type DGQuotientModule,
        The DG quotient module N / image(f) with the induced differential.

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

Equivalently, this is dgQuotientModule(target f, image f). The coker spelling
is an alias for cokernel and invokes the same method.

A nontrivial example: over R = k[x, y]/(x^2, y^2), multiplication by x on the
Koszul DG module KM has cokernel equal to KM / x \cdot KM, which at the natural
level is KM \otimes_R R/(x) -- the base change of KM mod x:

+--------------------------------------------------+
|i1 : R = ZZ/101[x, y] / ideal(x^2, y^2)           |
|                                                  |
|o1 = R                                            |
|                                                  |
|o1 : QuotientRing                                 |
+--------------------------------------------------+
|i2 : A = koszulComplexDGA R                       |
|                                                  |
|o2 = {Ring => R                          }        |
|      Underlying algebra => R[T   ..T   ]         |
|                               1,1   1,2          |
|      Differential => {x, y}                      |
|                                                  |
|o2 : DGAlgebra                                    |
+--------------------------------------------------+
|i3 : KM = koszulComplexDGM R^1                    |
|                                                  |
|o3 = {Base ring => R                    }         |
|      DG algebra => R[T   ..T   ]                 |
|                       1,1   1,2                  |
|                                       1          |
|      Natural module => (R[T   ..T   ])           |
|                            1,1   1,2             |
|      Generator degrees => {{0, 0}}               |
|      Differentials on gens => {0}                |
|                                                  |
|o3 : DGModule                                     |
+--------------------------------------------------+
|i4 : mx = dgModuleMap(KM, KM, x * id_(KM.natural))|
|                                                  |
|                               1                  |
|o4 = {Source => (R[T   ..T   ]) }                 |
|                    1,1   1,2                     |
|                               1                  |
|      Target => (R[T   ..T   ])                   |
|                    1,1   1,2                     |
|      Natural => | x |                            |
|                                                  |
|o4 : DGModuleMap                                  |
+--------------------------------------------------+
|i5 : Q = cokernel mx                              |
|                                                  |
|o5 = DGQuotientModule Q = M / S                   |
|     Q.natural = cokernel | x |                   |
|     Degrees   = {{0, 0}}                         |
|                                                  |
|o5 : DGQuotientModule                             |
+--------------------------------------------------+
|i6 : isWellDefined Q                              |
|                                                  |
|o6 = true                                         |
+--------------------------------------------------+
|i7 : ambient Q === KM                             |
|                                                  |
|o7 = true                                         |
+--------------------------------------------------+
|i8 : presentation Q.natural                       |
|                                                  |
|o8 = | x |                                        |
|                                                  |
|                           1                    1 |
|o8 : Matrix (R[T   ..T   ])  <-- (R[T   ..T   ])  |
|                1,1   1,2            1,1   1,2    |
+--------------------------------------------------+

The induced differential on Q is well-defined because mx commutes with the
differential, and it can be realized as an ordinary chain complex via
toComplex(DGQuotientModule),:

+-------------------------------------------------------------------+
|i9 : C = toComplex Q                                               |
|                                                                   |
|o9 = cokernel | x | <-- cokernel {1} | x 0 | <-- cokernel {2} | x ||
|                                 {1} | 0 x |                       |
|     0                                           2                 |
|                        1                                          |
|                                                                   |
|o9 : Complex                                                       |
+-------------------------------------------------------------------+
|i10 : apply(0..(maxDegree Q), n -> prune HH_n C)                   |
|                                                                   |
|o10 = (cokernel | y x |, cokernel | y x 0 0 |, cokernel | y x |)   |
|                                  | 0 0 y x |                      |
|                                                                   |
|o10 : Sequence                                                     |
+-------------------------------------------------------------------+

For a DG submodule inclusion S \hookrightarrow M, the cokernel is exactly the
DG quotient module M / S:

+-----------------------------------------------+
|i11 : Sfull = dgSubmodule(KM, id_(KM.natural));|
+-----------------------------------------------+
|i12 : isZero cokernel (inclusion Sfull)        |
|                                               |
|o12 = true                                     |
+-----------------------------------------------+

See also
========

  * Image, kernel, and cokernel of DG module maps
    -- Building DG submodules and DG quotient
    modules from a DG module map
  * image(DGModuleMap) -- Image of a DG module
    map as a DG submodule of its target
  * kernel(DGModuleMap) -- Kernel of a DG
    module map as a DG submodule of its source
  * DGQuotientModule -- The class of quotient DG
    modules M / S
  * DGModule / DGSubmodule -- Quotient DG
    module: M / S

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

  * cokernel(DGModuleMap) -- Cokernel of a DG
    module map as a DG quotient module of its target
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4119:0.

Homology of DG modules and DG module maps -- Computing H_n and H_* for DG modules, DG submodules, DG quotient modules, and DG module maps
*****************************************************************************************************************************************

For a DG module M over a DG algebra A, the package supports two parallel views
of homology:

HH_ZZ DGModule, returns a single degree H_n(M) as a
module over the base ring A.ring. This is the natural per-degree shape and
matches the convention of HH_ZZ DGAlgebra.

See HH DGModule, (equivalently homologyModule)
returns the full graded object H_*(M) assembled as a module
over the homology algebra HH(A), with the HH(A)-action coming from
multiplication by cycle classes.

Maps f : M -> N of DG modules induce maps on homology at each level:
homology(DGModuleMap,ZZ), returns the induced
map H_n(M) -> H_n(N) as a map of A.ring-modules, and HH DGModuleMap,
assembles those pieces into a map of HH(A)-modules.

For quotients, see HH_ZZ DGQuotientModule, and
HH DGQuotientModule, (equivalently
homologyModule(DGQuotientModule)) work the same way,
using toComplex, to reduce to an underlying complex.  A
DGSubmodule, is a DGModule, so its homology is
computed by the DG module methods directly.

To extract an explicit representative of a given homology class, use
homologyClass(DGModule,Vector),; given a
cycle in M.natural it returns the corresponding element of prune homology(n,
M).

+---------------------------------------------------------------+
|i1 : R = QQ[x, y]/ideal(x^2, y^2)                              |
|                                                               |
|o1 = R                                                         |
|                                                               |
|o1 : QuotientRing                                              |
+---------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                    |
|                                                               |
|o2 = {Ring => R                          }                     |
|      Underlying algebra => R[T   ..T   ]                      |
|                               1,1   1,2                       |
|      Differential => {x, y}                                   |
|                                                               |
|o2 : DGAlgebra                                                 |
+---------------------------------------------------------------+
|i3 : k = R^1 / ideal(x, y)                                     |
|                                                               |
|o3 = cokernel | x y |                                          |
|                                                               |
|                            1                                  |
|o3 : R-module, quotient of R                                   |
+---------------------------------------------------------------+
|i4 : M = minimalSemifreeResolution(A, k, EndDegree => 2)       |
|                                                               |
|o4 = {Base ring => R                                          }|
|      DG algebra => R[T   ..T   ]                              |
|                       1,1   1,2                               |
|                                       3                       |
|      Natural module => (R[T   ..T   ])                        |
|                            1,1   1,2                          |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}}            |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |} |
|                                   |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |
|                                                               |
|o4 : DGModule                                                  |
+---------------------------------------------------------------+
|i5 : H0 = prune homology(0, M)                                 |
|                                                               |
|o5 = cokernel | y x |                                          |
|                                                               |
|                            1                                  |
|o5 : R-module, quotient of R                                   |
+---------------------------------------------------------------+
|i6 : numgens H0 == 1                                           |
|                                                               |
|o6 = true                                                      |
+---------------------------------------------------------------+
|i7 : idM = identityDGModuleMap M                               |
|                                                               |
|                               3                               |
|o7 = {Source => (R[T   ..T   ])  }                             |
|                    1,1   1,2                                  |
|                               3                               |
|      Target => (R[T   ..T   ])                                |
|                    1,1   1,2                                  |
|      Natural => {0, 0} | 1 0 0 |                              |
|                 {2, 2} | 0 1 0 |                              |
|                 {2, 2} | 0 0 1 |                              |
|                                                               |
|o7 : DGModuleMap                                               |
+---------------------------------------------------------------+
|i8 : h0 = homology(idM, 0)                                     |
|                                                               |
|o8 = | 1 |                                                     |
|                                                               |
|o8 : Matrix k <-- k                                            |
+---------------------------------------------------------------+
|i9 : h0 == id_(source h0)                                      |
|                                                               |
|o9 = true                                                      |
+---------------------------------------------------------------+

The identity on M induces the identity on every H_n(M), a baseline sanity check
that each of the pieces fits together.

See also
========

  * HH DGModuleMap -- The induced map on graded homology
    modules over HH(A)
  * HH_ZZ DGAlgebra -- Computes the homology of a DG
    algebra as a module
  * HH DGAlgebra -- The homology algebra of a DG algebra
  * homologyModule -- Compute the homology of a DGModule
    as a module over a DGAlgebra.
  * homologyClass -- Computes the element of the homology
    algebra corresponding to a cycle in a DGAlgebra.

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4185:0.

HH_ZZ DGModule -- The degree-n homology of a DG module as a module over the base ring
*************************************************************************************

  * Function: homology (Macaulay2Doc),
  * Usage:
        H = homology(n, M)
  * Inputs:
      * n, an integer (Macaulay2Doc), A homological degree.
      * M, an instance of the type DGModule, A DG module over
        a DG algebra A.
  * Outputs:
      * H, a module (Macaulay2Doc), The module H_n(M) = ker(d_n)
        / image(d_{n+1}), presented as a module over A.ring.

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

This is the per-degree homology: the differential d_n : M_n -> M_{n-1} is built
via moduleDifferential, and H_n(M) is obtained by applying the built-in M2
homology method to the adjacent pair (d_n, d_{n+1}).  The resulting module
lives over A.ring; use prune(Module) (Macaulay2Doc),
to minimize the presentation.

Because DGSubmodule, is a subtype of DGModule,
this method also handles DG submodules directly.

+------------------------------------------+
|i1 : R = QQ[x, y, z]                      |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,3  |
|      Differential => {x, y, z}           |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : KM = koszulComplexDGM R^1            |
|                                          |
|o3 = {Base ring => R                    } |
|      DG algebra => R[T   ..T   ]         |
|                       1,1   1,3          |
|                                       1  |
|      Natural module => (R[T   ..T   ])   |
|                            1,1   1,3     |
|      Generator degrees => {{0, 0}}       |
|      Differentials on gens => {0}        |
|                                          |
|o3 : DGModule                             |
+------------------------------------------+
|i4 : prune homology(0, KM)                |
|                                          |
|o4 = cokernel | z y x |                   |
|                                          |
|                            1             |
|o4 : R-module, quotient of R              |
+------------------------------------------+
|i5 : prune homology(1, KM) == 0           |
|                                          |
|o5 = true                                 |
+------------------------------------------+
|i6 : prune homology(2, KM) == 0           |
|                                          |
|o6 = true                                 |
+------------------------------------------+

For the Koszul complex on a regular sequence, only H_0 = R/(x,y,z) is nonzero;
this recovers the standard fact.

+---------------------------------------------------------+
|i7 : R2 = ZZ/101[x]                                      |
|                                                         |
|o7 = R2                                                  |
|                                                         |
|o7 : PolynomialRing                                      |
+---------------------------------------------------------+
|i8 : A2 = koszulComplexDGA R2                            |
|                                                         |
|o8 = {Ring => R2                    }                    |
|      Underlying algebra => R2[T   ]                     |
|                                1,1                      |
|      Differential => {x}                                |
|                                                         |
|o8 : DGAlgebra                                           |
+---------------------------------------------------------+
|i9 : M = freeDGModule(A2, {0, 1})                        |
|                                                         |
|o9 = {Base ring => R2                      }             |
|      DG algebra => R2[T   ]                             |
|                        1,1                              |
|                                  2                      |
|      Natural module => (R2[T   ])                       |
|                             1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}              |
|      Differentials on gens => {0, 0}                    |
|                                                         |
|o9 : DGModule                                            |
+---------------------------------------------------------+
|i10 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                         |
|o10 = {| 1 |, | 0 |}                                     |
|       | 0 |  | 1 |                                      |
|                                                         |
|o10 : List                                               |
+---------------------------------------------------------+
|i11 : setDiff(M, {0, x * natGens#0})                     |
|                                                         |
|o11 = {Base ring => R2                      }            |
|       DG algebra => R2[T   ]                            |
|                         1,1                             |
|                                   2                     |
|       Natural module => (R2[T   ])                      |
|                              1,1                        |
|       Generator degrees => {{0, 0}, {1, 0}}             |
|       Differentials on gens => {0, | x |}               |
|                                    | 0 |                |
|                                                         |
|o11 : DGModule                                           |
+---------------------------------------------------------+
|i12 : numgens prune homology(0, M)                       |
|                                                         |
|o12 = 1                                                  |
+---------------------------------------------------------+
|i13 : numgens prune homology(1, M)                       |
|                                                         |
|o13 = 1                                                  |
+---------------------------------------------------------+

See also
========

  * Homology of DG modules and DG module maps
    -- Computing H_n and H_* for DG modules, DG submodules, DG
    quotient modules, and DG module maps
  * HH DGModule -- The graded homology of a DG module as a
    module over HH(A)
  * homology(DGModuleMap,ZZ) -- The
    induced map on degree-n homology of a DG module map
  * HH_ZZ DGQuotientModule -- The degree-n
    homology of a DG quotient module
  * HH_ZZ DGAlgebra -- Computes the homology of a DG
    algebra as a module
  * moduleDifferential -- The hom-degree-n
    differential of a DG module as a matrix over the base ring

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

  * HH_ZZ DGModule -- The degree-n homology of a DG
    module as a module over the base ring
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4241:0.

HH DGModule -- The graded homology of a DG module as a module over HH(A)
************************************************************************

  * Function: homology (Macaulay2Doc),
  * Usage:
        HM = homology M
        HM = homologyModule M
  * Inputs:
      * M, an instance of the type DGModule, A DG module over
        a DG algebra A.
  * Outputs:
      * HM, a module (Macaulay2Doc), The graded homology H_*(M)
        packaged as a module over the homology algebra HH(A).  The HH(A)-action
        comes from multiplication by cycle classes of A on M.

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

The two names homology M and homologyModule M produce the same object and are
provided as aliases, matching the analogous convention for DG algebras in which
HH DGAlgebra, returns homologyAlgebra.

For per-degree homology as an A.ring-module, use HH_ZZ DGModule.

A fast path is taken when M came from koszulComplexDGM,
and has vanishing generator differentials: in that case the result is computed
directly from M.module via homologyModule(DGAlgebra,Module).
Otherwise the method builds the HH(A)-module presentation
degree by degree, using the action of each cycle class of A on M.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y]/ideal(x^2, y^2)                                            |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o2 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,2                                     |
|      Differential => {x, y}                                                 |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : k = R^1 / ideal(x, y)                                                   |
|                                                                             |
|o3 = cokernel | x y |                                                        |
|                                                                             |
|                            1                                                |
|o3 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+
|i4 : M = minimalSemifreeResolution(A, k, EndDegree => 2)                     |
|                                                                             |
|o4 = {Base ring => R                                          }              |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       3                                     |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}}                          |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |}               |
|                                   |     0    |  |     0    |                |
|                                   |     0    |  |     0    |                |
|                                                                             |
|o4 : DGModule                                                                |
+-----------------------------------------------------------------------------+
|i5 : HM = homology M                                                         |
|Finding easy relations           :  -- used 0.156934s (cpu); 0.0913718s      |
|                                                                             |
|o5 = cokernel {0, 0} | X_2 X_1 0   0   0   0   |                             |
|              {3, 4} | 0   0   X_1 X_2 0   0   |                             |
|              {3, 4} | 0   0   0   X_1 0   X_2 |                             |
|              {3, 4} | 0   0   0   0   X_2 X_1 |                             |
|                                                                             |
|                                                4                            |
|o5 : QQ[X ..X ]-module, quotient of (QQ[X ..X ])                             |
|         1   2                           1   2                               |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i6 : ring HM === HH A                                                        |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+
|i7 : HM' = homologyModule M                                                  |
|                                                                             |
|o7 = cokernel {0, 0} | X_2 X_1 0   0   0   0   |                             |
|              {3, 4} | 0   0   X_1 X_2 0   0   |                             |
|              {3, 4} | 0   0   0   X_1 0   X_2 |                             |
|              {3, 4} | 0   0   0   0   X_2 X_1 |                             |
|                                                                             |
|                                                4                            |
|o7 : QQ[X ..X ]-module, quotient of (QQ[X ..X ])                             |
|         1   2                           1   2                               |
+-----------------------------------------------------------------------------+
|i8 : HM == HM'                                                               |
|                                                                             |
|o8 = true                                                                    |
+-----------------------------------------------------------------------------+

The ring of the result is HH(A), the homology algebra of the underlying DG
algebra.

Caveat
======

The general path currently requires M.natural to be a free A.natural-module (or
M to be a koszulComplexDGM, with zero generator
differentials).

See also
========

  * Homology of DG modules and DG module maps
    -- Computing H_n and H_* for DG modules, DG submodules, DG
    quotient modules, and DG module maps
  * HH_ZZ DGModule -- The degree-n homology of a DG
    module as a module over the base ring
  * HH DGAlgebra -- The homology algebra of a DG algebra
  * homologyModule -- Compute the homology of a DGModule
    as a module over a DGAlgebra.
  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.

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

  * HH DGModule -- The graded homology of a DG module as a
    module over HH(A)
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4299:0.

homology(DGModuleMap,ZZ) -- The induced map on degree-n homology of a DG module map
***********************************************************************************

  * Function: homology (Macaulay2Doc),
  * Usage:
        h = homology(f, n)
  * Inputs:
      * f, an instance of the type DGModuleMap, A map M ->
        N of DG modules over a common DG algebra A.
      * n, an integer (Macaulay2Doc), A homological degree.
  * Outputs:
      * h, a matrix (Macaulay2Doc), The induced map H_n(f) :
        H_n(M) -> H_n(N), presented as a morphism of A.ring-modules.

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

Computed via inducedMap (Macaulay2Doc), from the chain map
toComplexMap(f, n) applied to the pair of per-degree homology modules.  Since a
chain map sends cycles to cycles and boundaries to boundaries, the induced map
is well defined.

The identity DG module map induces the identity on each H_n; the zero DG module
map induces the zero map on each H_n.  Composition respects homology:
homology(g * f, n) == homology(g, n) * homology(f, n).

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y]/ideal(x^2, y^2)                                            |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o2 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,2                                     |
|      Differential => {x, y}                                                 |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : k = R^1 / ideal(x, y)                                                   |
|                                                                             |
|o3 = cokernel | x y |                                                        |
|                                                                             |
|                            1                                                |
|o3 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+
|i4 : M = minimalSemifreeResolution(A, k, EndDegree => 3)                     |
|                                                                             |
|o4 = {Base ring => R                                                         |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       6                                     |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}, {4, 4}, {4, 4}, {4, 4}}  |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |, |     0    |, |
|                                   |     0    |  |     0    |  | xT_(1,1) |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                                                             |
|o4 : DGModule                                                                |
|-----------------------------------------------------------------------------|
|                           }                                                 |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
||     0    |, |     0    |}                                                  |
|| yT_(1,2) |  |     0    |                                                   |
|| xT_(1,1) |  | yT_(1,2) |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
+-----------------------------------------------------------------------------+
|i5 : idM = identityDGModuleMap M                                             |
|                                                                             |
|                               6                                             |
|o5 = {Source => (R[T   ..T   ])        }                                     |
|                    1,1   1,2                                                |
|                               6                                             |
|      Target => (R[T   ..T   ])                                              |
|                    1,1   1,2                                                |
|      Natural => {0, 0} | 1 0 0 0 0 0 |                                      |
|                 {2, 2} | 0 1 0 0 0 0 |                                      |
|                 {2, 2} | 0 0 1 0 0 0 |                                      |
|                 {4, 4} | 0 0 0 1 0 0 |                                      |
|                 {4, 4} | 0 0 0 0 1 0 |                                      |
|                 {4, 4} | 0 0 0 0 0 1 |                                      |
|                                                                             |
|o5 : DGModuleMap                                                             |
+-----------------------------------------------------------------------------+
|i6 : zM = zeroDGModuleMap(M, M)                                              |
|                                                                             |
|                               6                                             |
|o6 = {Source => (R[T   ..T   ]) }                                            |
|                    1,1   1,2                                                |
|                               6                                             |
|      Target => (R[T   ..T   ])                                              |
|                    1,1   1,2                                                |
|      Natural => 0                                                           |
|                                                                             |
|o6 : DGModuleMap                                                             |
+-----------------------------------------------------------------------------+
|i7 : h0id = homology(idM, 0)                                                 |
|                                                                             |
|o7 = | 1 |                                                                   |
|                                                                             |
|o7 : Matrix k <-- k                                                          |
+-----------------------------------------------------------------------------+
|i8 : h0id == id_(source h0id)                                                |
|                                                                             |
|o8 = true                                                                    |
+-----------------------------------------------------------------------------+
|i9 : h0z = homology(zM, 0)                                                   |
|                                                                             |
|o9 = 0                                                                       |
|                                                                             |
|o9 : Matrix k <-- k                                                          |
+-----------------------------------------------------------------------------+
|i10 : h0z == map(target h0z, source h0z, 0)                                  |
|                                                                             |
|o10 = true                                                                   |
+-----------------------------------------------------------------------------+

Multiplication by x on a minimal semifree resolution of k = R/(x, y) induces
the zero map on H_0 = k, because x kills k.

+----------------------------------------------------------+
|i11 : natGens = apply(rank M.natural, i -> (M.natural)_i) |
|                                                          |
|o11 = {| 1 |, | 0 |, | 0 |, | 0 |, | 0 |, | 0 |}          |
|       | 0 |  | 1 |  | 0 |  | 0 |  | 0 |  | 0 |           |
|       | 0 |  | 0 |  | 1 |  | 0 |  | 0 |  | 0 |           |
|       | 0 |  | 0 |  | 0 |  | 1 |  | 0 |  | 0 |           |
|       | 0 |  | 0 |  | 0 |  | 0 |  | 1 |  | 0 |           |
|       | 0 |  | 0 |  | 0 |  | 0 |  | 0 |  | 1 |           |
|                                                          |
|o11 : List                                                |
+----------------------------------------------------------+
|i12 : xMap = dgModuleMap(M, M, apply(natGens, g -> x * g))|
|                                                          |
|                                6                         |
|o12 = {Source => (R[T   ..T   ])        }                 |
|                     1,1   1,2                            |
|                                6                         |
|       Target => (R[T   ..T   ])                          |
|                     1,1   1,2                            |
|       Natural => {0, 0} | x 0 0 0 0 0 |                  |
|                  {2, 2} | 0 x 0 0 0 0 |                  |
|                  {2, 2} | 0 0 x 0 0 0 |                  |
|                  {4, 4} | 0 0 0 x 0 0 |                  |
|                  {4, 4} | 0 0 0 0 x 0 |                  |
|                  {4, 4} | 0 0 0 0 0 x |                  |
|                                                          |
|o12 : DGModuleMap                                         |
+----------------------------------------------------------+
|i13 : h0x = homology(xMap, 0)                             |
|                                                          |
|o13 = 0                                                   |
|                                                          |
|o13 : Matrix k <-- k                                      |
+----------------------------------------------------------+
|i14 : h0x == map(target h0x, source h0x, 0)               |
|                                                          |
|o14 = true                                                |
+----------------------------------------------------------+

See also
========

  * Homology of DG modules and DG module maps
    -- Computing H_n and H_* for DG modules, DG submodules, DG
    quotient modules, and DG module maps
  * HH DGModuleMap -- The induced map on graded homology
    modules over HH(A)
  * HH_ZZ DGModule -- The degree-n homology of a DG
    module as a module over the base ring
  * toComplexMap -- Construct the ComplexMap associated to
    a DGAlgebraMap

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

  * homology(DGModuleMap,ZZ) -- The
    induced map on degree-n homology of a DG module map
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4354:0.

HH_ZZ DGQuotientModule -- The degree-n homology of a DG quotient module
***********************************************************************

  * Function: homology (Macaulay2Doc),
  * Usage:
        H = homology(n, Q)
  * Inputs:
      * n, an integer (Macaulay2Doc), A homological degree.
      * Q, an instance of the type DGQuotientModule, A
        DG quotient module M / S over a DG algebra A.
  * Outputs:
      * H, a module (Macaulay2Doc), The module H_n(Q), presented
        as a module over A.ring.

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

Implemented via HH_n (toComplex Q).  Since the underlying natural module is a
cokernel rather than a free module, the differentials of Q are expressed
through toComplex, and the standard M2 HH_n is applied.

+--------------------------------------------------------+
|i1 : R = ZZ/101[x]                                      |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                    }                    |
|      Underlying algebra => R[T   ]                     |
|                               1,1                      |
|      Differential => {x}                               |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                        |
|                                                        |
|o3 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, 0}                   |
|                                                        |
|o3 : DGModule                                           |
+--------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                        |
|o4 = {| 1 |, | 0 |}                                     |
|      | 0 |  | 1 |                                      |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : setDiff(M, {0, x * natGens#0})                     |
|                                                        |
|o5 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, | x |}               |
|                                   | 0 |                |
|                                                        |
|o5 : DGModule                                           |
+--------------------------------------------------------+
|i6 : S = dgSubmodule(M, (id_(M.natural))_{1})           |
|                                                        |
|o6 = DGSubmodule of ambient DGModule                    |
|     Degrees  => {{1, 0}, {0, 0}}                       |
|                          2                             |
|     natural  => (R[T   ])                              |
|                     1,1                                |
|     inclusion => {0, 0} | 0 x |                        |
|                  {1, 0} | 1 0 |                        |
|                                                        |
|o6 : DGSubmodule                                        |
+--------------------------------------------------------+
|i7 : Q = M / S                                          |
|                                                        |
|o7 = DGQuotientModule Q = M / S                         |
|     Q.natural = cokernel {0, 0} | 0 x |                |
|                          {1, 0} | 1 0 |                |
|     Degrees   = {{0, 0}, {1, 0}}                       |
|                                                        |
|o7 : DGQuotientModule                                   |
+--------------------------------------------------------+
|i8 : h0 = prune homology(0, Q)                          |
|                                                        |
|o8 = cokernel | x 0 0 |                                 |
|                                                        |
|                            1                           |
|o8 : R-module, quotient of R                            |
+--------------------------------------------------------+
|i9 : h1 = prune homology(1, Q)                          |
|                                                        |
|o9 = cokernel | x 0 |                                   |
|                                                        |
|                            1                           |
|o9 : R-module, quotient of R                            |
+--------------------------------------------------------+
|i10 : h2 = prune homology(2, Q)                         |
|                                                        |
|o10 = 0                                                 |
|                                                        |
|o10 : R-module                                          |
+--------------------------------------------------------+
|i11 : numgens h0 == 1                                   |
|                                                        |
|o11 = true                                              |
+--------------------------------------------------------+
|i12 : numgens h1 == 1                                   |
|                                                        |
|o12 = true                                              |
+--------------------------------------------------------+
|i13 : h2 == 0                                           |
|                                                        |
|o13 = true                                              |
+--------------------------------------------------------+

With S acyclic and H_0(M) = R/x, the quotient Q = M/S has H_0(Q) = R/x and
H_1(Q) = R/x, both equal to the residue field k = ZZ/101 (one generator each,
torsion), and H_2(Q) = 0.

See also
========

  * Homology of DG modules and DG module maps
    -- Computing H_n and H_* for DG modules, DG submodules, DG
    quotient modules, and DG module maps
  * HH DGQuotientModule -- The graded homology of a
    DG quotient module
  * HH_ZZ DGModule -- The degree-n homology of a DG
    module as a module over the base ring
  * toComplex(DGQuotientModule), --
    Export a DG quotient module to a Complex

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

  * HH_ZZ DGQuotientModule -- The degree-n
    homology of a DG quotient module
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4404:0.

HH DGQuotientModule -- The graded homology of a DG quotient module
******************************************************************

  * Function: homology (Macaulay2Doc),
  * Usage:
        HQ = homology Q
        HQ = homologyModule Q
  * Inputs:
      * Q, an instance of the type DGQuotientModule, A
        DG quotient module M / S over a DG algebra A.
  * Outputs:
      * HQ, a module (Macaulay2Doc), The graded homology H_*(Q)
        packaged as a module over HH(A).

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

Implemented by taking toComplex, and assembling the per-degree
homologies HH_i(toComplex Q) into a direct sum, then tensoring each piece with
HH(A) along A.ring -> HH(A). The two names homology Q and homologyModule Q are
aliases, matching HH DGModule.

Because Q.natural is a cokernel rather than a free A.natural-module, the
general cycle-action construction used for homologyModule(DGModule),
does not apply; the result captures the R-module structure and the
HH(A) action coming from A.ring -> HH(A) only.

+--------------------------------------------------------+
|i1 : R = ZZ/101[x]                                      |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                    }                    |
|      Underlying algebra => R[T   ]                     |
|                               1,1                      |
|      Differential => {x}                               |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                        |
|                                                        |
|o3 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, 0}                   |
|                                                        |
|o3 : DGModule                                           |
+--------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                        |
|o4 = {| 1 |, | 0 |}                                     |
|      | 0 |  | 1 |                                      |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : setDiff(M, {0, x * natGens#0})                     |
|                                                        |
|o5 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, | x |}               |
|                                   | 0 |                |
|                                                        |
|o5 : DGModule                                           |
+--------------------------------------------------------+
|i6 : S = dgSubmodule(M, (id_(M.natural))_{1})           |
|                                                        |
|o6 = DGSubmodule of ambient DGModule                    |
|     Degrees  => {{1, 0}, {0, 0}}                       |
|                          2                             |
|     natural  => (R[T   ])                              |
|                     1,1                                |
|     inclusion => {0, 0} | 0 x |                        |
|                  {1, 0} | 1 0 |                        |
|                                                        |
|o6 : DGSubmodule                                        |
+--------------------------------------------------------+
|i7 : Q = M / S                                          |
|                                                        |
|o7 = DGQuotientModule Q = M / S                         |
|     Q.natural = cokernel {0, 0} | 0 x |                |
|                          {1, 0} | 1 0 |                |
|     Degrees   = {{0, 0}, {1, 0}}                       |
|                                                        |
|o7 : DGQuotientModule                                   |
+--------------------------------------------------------+
|i8 : HQ = homology Q                                    |
|                                                        |
|       ZZ 2                                             |
|o8 = (---)                                              |
|      101                                               |
|                                                        |
|      ZZ                                                |
|o8 : ----module, free                                   |
|     101                                                |
+--------------------------------------------------------+
|i9 : ring HQ === HH A                                   |
|                                                        |
|o9 = true                                               |
+--------------------------------------------------------+
|i10 : HQ' = homologyModule Q                            |
|                                                        |
|        ZZ 2                                            |
|o10 = (---)                                             |
|       101                                              |
|                                                        |
|       ZZ                                               |
|o10 : ----module, free                                  |
|      101                                               |
+--------------------------------------------------------+
|i11 : HQ == HQ'                                         |
|                                                        |
|o11 = true                                              |
+--------------------------------------------------------+

See also
========

  * Homology of DG modules and DG module maps
    -- Computing H_n and H_* for DG modules, DG submodules, DG
    quotient modules, and DG module maps
  * HH_ZZ DGQuotientModule -- The degree-n
    homology of a DG quotient module
  * HH DGModule -- The graded homology of a DG module as a
    module over HH(A)
  * toComplex(DGQuotientModule), --
    Export a DG quotient module to a Complex
  * homologyModule -- Compute the homology of a DGModule
    as a module over a DGAlgebra.

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

  * HH DGQuotientModule -- The graded homology of a
    DG quotient module
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4454:0.

homologyClass(DGModule,Vector) -- The homology class of a cycle in a DG module
******************************************************************************

  * Function: homologyClass,
  * Usage:
        h = homologyClass(M, z)
  * Inputs:
      * M, an instance of the type DGModule, A free DG module
        over a DG algebra A.
      * z, a vector (Macaulay2Doc), A cycle in M.natural; that
        is, an element z of homological degree d with diff(M, z) == 0.
  * Outputs:
      * h, The corresponding element of prune homology(d, M). Boundaries go to
        zero; the zero vector returns 0_(prune homology(0, M)) by convention.

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

This is the DG module analogue of homologyClass(DGAlgebra,RingElement).
It expresses the cycle z in the basis of prune homology(d, M)
by solving zCol = pruneMat * hCoef + boundaryMat * t, where pruneMat is the
pruning map of H_d(M) and boundaryMat is the degree-d+1 differential.

An input that is not a cycle raises an error.

+--------------------------------------------------------+
|i1 : R = ZZ/101[x]                                      |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                    }                    |
|      Underlying algebra => R[T   ]                     |
|                               1,1                      |
|      Differential => {x}                               |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                        |
|                                                        |
|o3 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, 0}                   |
|                                                        |
|o3 : DGModule                                           |
+--------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                        |
|o4 = {| 1 |, | 0 |}                                     |
|      | 0 |  | 1 |                                      |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : setDiff(M, {0, x * natGens#0})                     |
|                                                        |
|o5 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, | x |}               |
|                                   | 0 |                |
|                                                        |
|o5 : DGModule                                           |
+--------------------------------------------------------+
|i6 : z = natGens#0                                      |
|                                                        |
|o6 = | 1 |                                              |
|     | 0 |                                              |
|                                                        |
|              2                                         |
|o6 : (R[T   ])                                          |
|         1,1                                            |
+--------------------------------------------------------+
|i7 : H = prune homology(0, M)                           |
|                                                        |
|o7 = cokernel | x 0 |                                   |
|                                                        |
|                            1                           |
|o7 : R-module, quotient of R                            |
+--------------------------------------------------------+
|i8 : h = homologyClass(M, z)                            |
|                                                        |
|o8 = | 1 |                                              |
|                                                        |
|o8 : H                                                  |
+--------------------------------------------------------+
|i9 : h != 0_H                                           |
|                                                        |
|o9 = true                                               |
+--------------------------------------------------------+

On a boundary, homologyClass returns zero.

+------------------------------------+
|i10 : b = x * natGens#0             |
|                                    |
|o10 = | x |                         |
|      | 0 |                         |
|                                    |
|               2                    |
|o10 : (R[T   ])                     |
|          1,1                       |
+------------------------------------+
|i11 : hb = homologyClass(M, b)      |
|                                    |
|o11 = 0                             |
|                                    |
|o11 : H                             |
+------------------------------------+
|i12 : hb == 0_(prune homology(0, M))|
|                                    |
|o12 = true                          |
+------------------------------------+

Caveat
======

Requires M to be a free DG module.

See also
========

  * Homology of DG modules and DG module maps
    -- Computing H_n and H_* for DG modules, DG submodules, DG
    quotient modules, and DG module maps
  * homologyClass(DGAlgebra,RingElement) -- Computes the
    element of the homology algebra corresponding to a cycle in a DGAlgebra.
  * HH_ZZ DGModule -- The degree-n homology of a DG
    module as a module over the base ring

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

  * homologyClass(DGModule,Vector),
    -- The homology class of a cycle in a DG module
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4506:0.

Pruning DG modules, submodules, quotients, and maps -- Minimizing presentations of DG types via prune and minimalPresentation
*****************************************************************************************************************************

For each DG type T (DG algebra, DG module, DG submodule, DG quotient module, DG
ideal, DG algebra map, DG module map), the package provides prune and its
synonym minimalPresentation.  The result is an object of the same type whose
underlying presentation has had redundancy removed, where possible.

Every call to prune caches a pruningMap in the cache table of the pruned
output, encoding the canonical comparison map (pruned) -> (original).  For
types where pruning does nothing (see below), the cached pruningMap is the
identity; for types where it does something, the pruningMap is a well-defined
DGModuleMap, (or DGAlgebraMap) whose
source is the pruned object and whose target is the original. This mirrors the
convention used by prune applied to Complex objects from the Complexes package
for Complex objects.

The two active cases are:

prune(DGSubmodule), trims the inclusion matrix to
a minimal generating set of its column span.  When the inclusion matrix is
already minimal, prune is the identity.

See prune(DGQuotientModule), first prunes the
relations submodule and then additionally prunes toComplex Qp at the complex
level, caching the result so that toComplex Qp returns a minimally presented
complex.

The no-op cases, installed so that pruning always commutes with every
constructor, are prune(DGModule),
prune(DGAlgebra), prune(DGAlgebraMap),
see prune(DGModuleMap),
and (already documented) prune(DGIdeal).

+----------------------------------------------------------------+
|i1 : R = ZZ/101[x, y]                                           |
|                                                                |
|o1 = R                                                          |
|                                                                |
|o1 : PolynomialRing                                             |
+----------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                     |
|                                                                |
|o2 = {Ring => R                          }                      |
|      Underlying algebra => R[T   ..T   ]                       |
|                               1,1   1,2                        |
|      Differential => {x, y}                                    |
|                                                                |
|o2 : DGAlgebra                                                  |
+----------------------------------------------------------------+
|i3 : Anat = A.natural                                           |
|                                                                |
|o3 = Anat                                                       |
|                                                                |
|o3 : PolynomialRing, 2 skew commutative variable(s)             |
+----------------------------------------------------------------+
|i4 : M = freeDGModule(A, {0})                                   |
|                                                                |
|o4 = {Base ring => R               }                            |
|      DG algebra => Anat                                        |
|                            1                                   |
|      Natural module => Anat                                    |
|      Generator degrees => {{0, 0}}                             |
|      Differentials on gens => {0}                              |
|                                                                |
|o4 : DGModule                                                   |
+----------------------------------------------------------------+
|i5 : S = dgSubmodule(M, matrix {{1_Anat, x_Anat, y_Anat}})      |
|                                                                |
|o5 = DGSubmodule of ambient DGModule                            |
|     Degrees  => {{0, 0}, {0, 1}, {0, 1}}                       |
|                     3                                          |
|     natural  => Anat                                           |
|     inclusion => | 1 x y |                                     |
|                                                                |
|o5 : DGSubmodule                                                |
+----------------------------------------------------------------+
|i6 : Sp = prune S                                               |
|                                                                |
|o6 = DGSubmodule of ambient DGModule                            |
|     Degrees  => {{0, 0}}                                       |
|                     1                                          |
|     natural  => Anat                                           |
|     inclusion => | 1 |                                         |
|                                                                |
|o6 : DGSubmodule                                                |
+----------------------------------------------------------------+
|i7 : numcols (inclusion S).natural                              |
|                                                                |
|o7 = 3                                                          |
+----------------------------------------------------------------+
|i8 : numcols (inclusion Sp).natural                             |
|                                                                |
|o8 = 1                                                          |
+----------------------------------------------------------------+
|i9 : image (inclusion S).natural == image (inclusion Sp).natural|
|                                                                |
|o9 = true                                                       |
+----------------------------------------------------------------+

The image submodule of M.natural is unchanged; the presentation of S is reduced
from three generators to one.

See also
========

  * prune(DGIdeal) -- Trim a DG ideal down to a
    minimal generating set
  * mingens(DGIdeal) -- Basic accessors on a DG
    ideal

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4572:0.

prune(DGSubmodule) -- Trim a DG submodule to a minimal generating set of its inclusion
**************************************************************************************

  * Function: prune (Macaulay2Doc),
  * Usage:
        Sp = prune S
        Sp = minimalPresentation S
  * Inputs:
      * S, an instance of the type DGSubmodule,
  * Optional inputs (Macaulay2Doc),:
      * Exclude (Macaulay2Doc), => ...,
        default value {},
  * Outputs:
      * Sp, an instance of the type DGSubmodule, A DG
        submodule of the same ambient DG module whose inclusion matrix has had
        A.natural-linearly redundant columns removed.

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

prune S computes mingens image S.inclusion.natural and builds a new DG
submodule from that reduced inclusion matrix.  The A.natural-span of the new
inclusion matrix equals the original: image Sp.inclusion.natural == image
S.inclusion.natural.

A pruningMap is cached in Sp.cache as a DGModuleMap, from Sp
to S; when the inclusion matrix is already minimal this is the identity on S
(and prune S === S).

Well-definedness (d-closure) and the underlying natural-level image are
preserved by pruning.

+----------------------------------------------------------------+
|i1 : R = ZZ/101[x, y]                                           |
|                                                                |
|o1 = R                                                          |
|                                                                |
|o1 : PolynomialRing                                             |
+----------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                     |
|                                                                |
|o2 = {Ring => R                          }                      |
|      Underlying algebra => R[T   ..T   ]                       |
|                               1,1   1,2                        |
|      Differential => {x, y}                                    |
|                                                                |
|o2 : DGAlgebra                                                  |
+----------------------------------------------------------------+
|i3 : Anat = A.natural                                           |
|                                                                |
|o3 = Anat                                                       |
|                                                                |
|o3 : PolynomialRing, 2 skew commutative variable(s)             |
+----------------------------------------------------------------+
|i4 : M = freeDGModule(A, {0})                                   |
|                                                                |
|o4 = {Base ring => R               }                            |
|      DG algebra => Anat                                        |
|                            1                                   |
|      Natural module => Anat                                    |
|      Generator degrees => {{0, 0}}                             |
|      Differentials on gens => {0}                              |
|                                                                |
|o4 : DGModule                                                   |
+----------------------------------------------------------------+
|i5 : S = dgSubmodule(M, matrix {{1_Anat, x_Anat, y_Anat}})      |
|                                                                |
|o5 = DGSubmodule of ambient DGModule                            |
|     Degrees  => {{0, 0}, {0, 1}, {0, 1}}                       |
|                     3                                          |
|     natural  => Anat                                           |
|     inclusion => | 1 x y |                                     |
|                                                                |
|o5 : DGSubmodule                                                |
+----------------------------------------------------------------+
|i6 : Sp = prune S                                               |
|                                                                |
|o6 = DGSubmodule of ambient DGModule                            |
|     Degrees  => {{0, 0}}                                       |
|                     1                                          |
|     natural  => Anat                                           |
|     inclusion => | 1 |                                         |
|                                                                |
|o6 : DGSubmodule                                                |
+----------------------------------------------------------------+
|i7 : numcols (inclusion Sp).natural                             |
|                                                                |
|o7 = 1                                                          |
+----------------------------------------------------------------+
|i8 : numcols (inclusion S).natural                              |
|                                                                |
|o8 = 3                                                          |
+----------------------------------------------------------------+
|i9 : image (inclusion S).natural == image (inclusion Sp).natural|
|                                                                |
|o9 = true                                                       |
+----------------------------------------------------------------+
|i10 : isWellDefined Sp                                          |
|                                                                |
|o10 = true                                                      |
+----------------------------------------------------------------+

minimalPresentation is a synonym for prune on DG submodules.

See also
========

  * Pruning DG modules, submodules, quotients, and maps
    -- Minimizing presentations
    of DG types via prune and minimalPresentation
  * prune(DGQuotientModule) -- Minimize the
    presentation of a DG quotient module
  * prune(DGModule) -- Pruning a DG module is the
    identity
  * dgSubmodule -- Construct a d-closed submodule of a DG
    module

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

  * prune(DGSubmodule) -- Trim a DG submodule to
    a minimal generating set of its inclusion
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4624:0.

prune(DGQuotientModule) -- Minimize the presentation of a DG quotient module
****************************************************************************

  * Function: prune (Macaulay2Doc),
  * Usage:
        Qp = prune Q
        Qp = minimalPresentation Q
  * Inputs:
      * Q, an instance of the type DGQuotientModule,
  * Optional inputs (Macaulay2Doc),:
      * Exclude (Macaulay2Doc), => ...,
        default value {},
  * Outputs:
      * Qp, an instance of the type DGQuotientModule,
        A DG quotient module of the same ambient DG module whose relations
        submodule has been pruned, and whose toComplex Qp has additionally been
        pruned at the complex level.

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

prune Q proceeds in two steps.  First, it prunes the relations submodule
Q.subDGModule using prune(DGSubmodule),; this
trims redundant columns from the inclusion matrix.  If the inclusion was
already minimal, Qp === Q.

Second, it computes prune (toComplex Qp) at the complex level and caches the
result in Qp.cache under the symbol prunedComplex.  After this, calling
toComplex Qp returns a minimally presented complex and pruning commutes with
toComplex: the complex-level prune of toComplex Qp is idempotent.

A pruningMap from Qp to Q is cached in Qp.cache as a DGModuleMap,
induced by the identity on M.natural.

+----------------------------------------------------------------------------+
|i1 : R = ZZ/101[x, y]                                                       |
|                                                                            |
|o1 = R                                                                      |
|                                                                            |
|o1 : PolynomialRing                                                         |
+----------------------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                                 |
|                                                                            |
|o2 = {Ring => R                          }                                  |
|      Underlying algebra => R[T   ..T   ]                                   |
|                               1,1   1,2                                    |
|      Differential => {x, y}                                                |
|                                                                            |
|o2 : DGAlgebra                                                              |
+----------------------------------------------------------------------------+
|i3 : Anat = A.natural                                                       |
|                                                                            |
|o3 = Anat                                                                   |
|                                                                            |
|o3 : PolynomialRing, 2 skew commutative variable(s)                         |
+----------------------------------------------------------------------------+
|i4 : M = freeDGModule(A, {0})                                               |
|                                                                            |
|o4 = {Base ring => R               }                                        |
|      DG algebra => Anat                                                    |
|                            1                                               |
|      Natural module => Anat                                                |
|      Generator degrees => {{0, 0}}                                         |
|      Differentials on gens => {0}                                          |
|                                                                            |
|o4 : DGModule                                                               |
+----------------------------------------------------------------------------+
|i5 : S = dgSubmodule(M, matrix {{1_Anat, x_Anat, y_Anat}})                  |
|                                                                            |
|o5 = DGSubmodule of ambient DGModule                                        |
|     Degrees  => {{0, 0}, {0, 1}, {0, 1}}                                   |
|                     3                                                      |
|     natural  => Anat                                                       |
|     inclusion => | 1 x y |                                                 |
|                                                                            |
|o5 : DGSubmodule                                                            |
+----------------------------------------------------------------------------+
|i6 : Q = M / S                                                              |
|                                                                            |
|o6 = DGQuotientModule Q = M / S                                             |
|     Q.natural = cokernel | 1 x y |                                         |
|     Degrees   = {{0, 0}}                                                   |
|                                                                            |
|o6 : DGQuotientModule                                                       |
+----------------------------------------------------------------------------+
|i7 : Qp = prune Q                                                           |
|                                                                            |
|o7 = DGQuotientModule Q = M / S                                             |
|     Q.natural = cokernel | 1 |                                             |
|     Degrees   = {{0, 0}}                                                   |
|                                                                            |
|o7 : DGQuotientModule                                                       |
+----------------------------------------------------------------------------+
|i8 : image (inclusion Qp.subDGModule).natural == image (inclusion S).natural|
|                                                                            |
|o8 = true                                                                   |
+----------------------------------------------------------------------------+

If the cokernel is secretly zero, pruning collapses toComplex Qp to the zero
complex, matching prune applied to Complex objects from the Complexes package
on Complex.

minimalPresentation is a synonym for prune on DG quotient modules.

See also
========

  * Pruning DG modules, submodules, quotients, and maps
    -- Minimizing presentations
    of DG types via prune and minimalPresentation
  * prune(DGSubmodule) -- Trim a DG submodule to
    a minimal generating set of its inclusion
  * dgQuotientModule -- Construct the quotient DG
    module M / S
  * DGModule / DGSubmodule -- Quotient DG
    module: M / S

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

  * prune(DGQuotientModule) -- Minimize the
    presentation of a DG quotient module
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4682:0.

prune(DGModule) -- Pruning a DG module is the identity
******************************************************

  * Function: prune (Macaulay2Doc),
  * Usage:
        Mp = prune M
        Mp = minimalPresentation M
  * Inputs:
      * M, an instance of the type DGModule,
  * Optional inputs (Macaulay2Doc),:
      * Exclude (Macaulay2Doc), => ...,
        default value {},
  * Outputs:
      * Mp, an instance of the type DGModule, The same DG
        module M.  A pruningMap equal to the identity DG module map on M is
        cached in M.cache.

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

DG modules as stored in this package (built from freeDGModule,
or koszulComplexDGM) carry no auxiliary
presentation data that prune could minimize; the method is installed as the
identity so that calling code can use prune uniformly across DG types.

Calling prune M has the side effect of caching an identity DGModuleMap,
under the symbol pruningMap in M.cache.

minimalPresentation is a synonym for prune.

+--------------------------------------------+
|i1 : R = ZZ/101[x]                          |
|                                            |
|o1 = R                                      |
|                                            |
|o1 : PolynomialRing                         |
+--------------------------------------------+
|i2 : A = koszulComplexDGA R                 |
|                                            |
|o2 = {Ring => R                    }        |
|      Underlying algebra => R[T   ]         |
|                               1,1          |
|      Differential => {x}                   |
|                                            |
|o2 : DGAlgebra                              |
+--------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})            |
|                                            |
|o3 = {Base ring => R                       }|
|      DG algebra => R[T   ]                 |
|                       1,1                  |
|                                 2          |
|      Natural module => (R[T   ])           |
|                            1,1             |
|      Generator degrees => {{0, 0}, {1, 0}} |
|      Differentials on gens => {0, 0}       |
|                                            |
|o3 : DGModule                               |
+--------------------------------------------+
|i4 : (prune M) === M                        |
|                                            |
|o4 = true                                   |
+--------------------------------------------+
|i5 : (minimalPresentation M) === M          |
|                                            |
|o5 = true                                   |
+--------------------------------------------+

See also
========

  * Pruning DG modules, submodules, quotients, and maps
    -- Minimizing presentations
    of DG types via prune and minimalPresentation
  * prune(DGSubmodule) -- Trim a DG submodule to
    a minimal generating set of its inclusion
  * prune(DGQuotientModule) -- Minimize the
    presentation of a DG quotient module

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

  * prune(DGModule) -- Pruning a DG module is the
    identity
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4723:0.

prune(DGAlgebra) -- Pruning a DG algebra is the identity
********************************************************

  * Function: prune (Macaulay2Doc),
  * Usage:
        Ap = prune A
        Ap = minimalPresentation A
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Optional inputs (Macaulay2Doc),:
      * Exclude (Macaulay2Doc), => ...,
        default value {},
  * Outputs:
      * Ap, an instance of the type DGAlgebra, The same DG
        algebra A.

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

DG algebras as stored in this package carry a fixed underlying graded algebra
and differential; there is no redundancy for prune to eliminate.  The method is
installed as the identity so that pruning commutes uniformly with every
constructor.

minimalPresentation is a synonym for prune.

+------------------------------------------+
|i1 : R = ZZ/101[x, y]                     |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : (prune A) === A                      |
|                                          |
|o3 = true                                 |
+------------------------------------------+
|i4 : (minimalPresentation A) === A        |
|                                          |
|o4 = true                                 |
+------------------------------------------+

See also
========

  * Pruning DG modules, submodules, quotients, and maps
    -- Minimizing presentations
    of DG types via prune and minimalPresentation
  * prune(DGIdeal) -- Trim a DG ideal down to a
    minimal generating set

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

  * prune(DGAlgebra) -- Pruning a DG algebra is
    the identity
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4756:0.

prune(DGAlgebraMap) -- Pruning a DG algebra map is the identity
***************************************************************

  * Function: prune (Macaulay2Doc),
  * Usage:
        fp = prune f
        fp = minimalPresentation f
  * Inputs:
      * f, an instance of the type DGAlgebraMap,
  * Optional inputs (Macaulay2Doc),:
      * Exclude (Macaulay2Doc), => ...,
        default value {},
  * Outputs:
      * fp, an instance of the type DGAlgebraMap, The same
        DG algebra map f.

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

Since prune(DGAlgebra), is the identity, and a
DGAlgebraMap, is stored as a ring map between the
underlying graded algebras of its source and target, there is nothing for prune
to minimize.  The method is installed as the identity so that pruning commutes
uniformly.

minimalPresentation is a synonym for prune.

+-----------------------------------------------------------+
|i1 : R = ZZ/101[x, y]                                      |
|                                                           |
|o1 = R                                                     |
|                                                           |
|o1 : PolynomialRing                                        |
+-----------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                |
|                                                           |
|o2 = {Ring => R                          }                 |
|      Underlying algebra => R[T   ..T   ]                  |
|                               1,1   1,2                   |
|      Differential => {x, y}                               |
|                                                           |
|o2 : DGAlgebra                                             |
+-----------------------------------------------------------+
|i3 : phi = identityDGAlgebraMap A                          |
|                                                           |
|o3 = map (R[T   ..T   ], R[T   ..T   ], {T   , T   , x, y})|
|             1,1   1,2      1,1   1,2     1,1   1,2        |
|                                                           |
|o3 : DGAlgebraMap                                          |
+-----------------------------------------------------------+
|i4 : (prune phi) === phi                                   |
|                                                           |
|o4 = true                                                  |
+-----------------------------------------------------------+
|i5 : (minimalPresentation phi) === phi                     |
|                                                           |
|o5 = true                                                  |
+-----------------------------------------------------------+

See also
========

  * Pruning DG modules, submodules, quotients, and maps
    -- Minimizing presentations
    of DG types via prune and minimalPresentation
  * prune(DGAlgebra) -- Pruning a DG algebra is
    the identity
  * DGAlgebraMap -- The class of DG algebra maps

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

  * prune(DGAlgebraMap) -- Pruning a DG algebra
    map is the identity
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4791:0.

prune(DGModuleMap) -- Pruning a DG module map is the identity
*************************************************************

  * Function: prune (Macaulay2Doc),
  * Usage:
        fp = prune f
        fp = minimalPresentation f
  * Inputs:
      * f, an instance of the type DGModuleMap,
  * Optional inputs (Macaulay2Doc),:
      * Exclude (Macaulay2Doc), => ...,
        default value {},
  * Outputs:
      * fp, an instance of the type DGModuleMap, The same
        DG module map f.

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

Since prune(DGModule), is the identity, and a
DGModuleMap, is stored as an A.natural-linear matrix between the
naturals of its source and target, there is nothing for prune to minimize.  The
method is installed as the identity so that pruning commutes uniformly.

minimalPresentation is a synonym for prune.

+--------------------------------------------+
|i1 : R = ZZ/101[x]                          |
|                                            |
|o1 = R                                      |
|                                            |
|o1 : PolynomialRing                         |
+--------------------------------------------+
|i2 : A = koszulComplexDGA R                 |
|                                            |
|o2 = {Ring => R                    }        |
|      Underlying algebra => R[T   ]         |
|                               1,1          |
|      Differential => {x}                   |
|                                            |
|o2 : DGAlgebra                              |
+--------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})            |
|                                            |
|o3 = {Base ring => R                       }|
|      DG algebra => R[T   ]                 |
|                       1,1                  |
|                                 2          |
|      Natural module => (R[T   ])           |
|                            1,1             |
|      Generator degrees => {{0, 0}, {1, 0}} |
|      Differentials on gens => {0, 0}       |
|                                            |
|o3 : DGModule                               |
+--------------------------------------------+
|i4 : idM = identityDGModuleMap M            |
|                                            |
|                         2                  |
|o4 = {Source => (R[T   ])      }            |
|                    1,1                     |
|                         2                  |
|      Target => (R[T   ])                   |
|                    1,1                     |
|      Natural => {0, 0} | 1 0 |             |
|                 {1, 0} | 0 1 |             |
|                                            |
|o4 : DGModuleMap                            |
+--------------------------------------------+
|i5 : (prune idM) === idM                    |
|                                            |
|o5 = true                                   |
+--------------------------------------------+
|i6 : (minimalPresentation idM) === idM      |
|                                            |
|o6 = true                                   |
+--------------------------------------------+

See also
========

  * Pruning DG modules, submodules, quotients, and maps
    -- Minimizing presentations
    of DG types via prune and minimalPresentation
  * prune(DGModule) -- Pruning a DG module is the
    identity
  * DGModuleMap -- The class of morphisms of DG modules
    over a common DG algebra

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

  * prune(DGModuleMap) -- Pruning a DG module
    map is the identity
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4827:0.

Well-definedness, acyclicity, and quasi-isomorphism -- Predicates that check DG-theoretic conditions on DG types
****************************************************************************************************************

The package exposes three families of predicates for checking conditions that
distinguish DG objects from their underlying graded / module-theoretic data.

See isWellDefined (Macaulay2Doc), — verifies that an object
satisfies the DG axioms appropriate to its type.  For a DGAlgebra,
or DGModule, the central check is that the stored
differential squares to zero on every generator.  For a DGSubmodule,
or DGQuotientModule, the check is
d-closure of the defining submodule; for a DGAlgebraMap, or
DGModuleMap, the check is the chain-map condition d \circ f
= f \circ d on every generator.

See isAcyclic, — returns true when a DG algebra or DG module has
H_i = 0 for all i >= 1 up to a finite bound.  For objects with infinite
hom-degree the user must supply EndDegree.

See isQuasiIsomorphism (Complexes), —
returns true when a DG algebra map or DG module map induces an isomorphism on
H_*.  The underlying check is performed on toComplexMap,
and inherits the Concentration option from the Complexes package.

All three predicates accept the option EndDegree, where
applicable; for finite-degree objects the default bound is maxDegree of the
object and no option is required.

+---------------------------------------------------+
|i1 : R = QQ[x, y, z]                               |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,3           |
|      Differential => {x, y, z}                    |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : isWellDefined A                               |
|                                                   |
|o3 = true                                          |
+---------------------------------------------------+
|i4 : isAcyclic A                                   |
|                                                   |
|o4 = true                                          |
+---------------------------------------------------+
|i5 : Anat = A.natural                              |
|                                                   |
|o5 = Anat                                          |
|                                                   |
|o5 : PolynomialRing, 3 skew commutative variable(s)|
+---------------------------------------------------+
|i6 : M = freeDGModule(A, {0})                      |
|                                                   |
|o6 = {Base ring => R               }               |
|      DG algebra => Anat                           |
|                            1                      |
|      Natural module => Anat                       |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o6 : DGModule                                      |
+---------------------------------------------------+
|i7 : S = dgSubmodule(M, matrix {{1_Anat}})         |
|                                                   |
|o7 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 0}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => | 1 |                            |
|                                                   |
|o7 : DGSubmodule                                   |
+---------------------------------------------------+
|i8 : Q = M / S                                     |
|                                                   |
|o8 = DGQuotientModule Q = M / S                    |
|     Q.natural = cokernel | 1 |                    |
|     Degrees   = {{0, 0}}                          |
|                                                   |
|o8 : DGQuotientModule                              |
+---------------------------------------------------+
|i9 : isWellDefined S                               |
|                                                   |
|o9 = true                                          |
+---------------------------------------------------+
|i10 : isWellDefined Q                              |
|                                                   |
|o10 = true                                         |
+---------------------------------------------------+
|i11 : phi = identityDGAlgebraMap A                 |
|                                                   |
|o11 = map (Anat, Anat, {T   , T   , T   , x, y, z})|
|                         1,1   1,2   1,3           |
|                                                   |
|o11 : DGAlgebraMap                                 |
+---------------------------------------------------+
|i12 : isWellDefined phi                            |
|                                                   |
|o12 = true                                         |
+---------------------------------------------------+
|i13 : isQuasiIsomorphism phi                       |
|                                                   |
|o13 = true                                         |
+---------------------------------------------------+

For a regular polynomial ring the Koszul DG algebra is acyclic and its identity
map is a quasi-isomorphism.  Both S and Q = M / S are well-defined because S is
d-closed.

See also
========

  * isWellDefined(DGIdeal) -- Verify that a
    DGIdeal has correct structure and is d-closed
  * isAcyclic(DGAlgebra) -- Determine whether a DG algebra
    has no higher homology
  * isQuasiIsomorphism(DGModuleMap), --
    Elementary predicates and constructors for DGModuleMaps

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4897:0.

isWellDefined(DGAlgebra) -- Check that a DG algebra has correct structure and a differential that squares to zero
*****************************************************************************************************************

  * Function: isWellDefined (Macaulay2Doc),
  * Usage:
        b = isWellDefined A
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), True when A has all
        expected structural keys with the correct types, the base ring of
        A.natural is compatible with A.ring, the differential lowers
        homological degree by one on every generator, and d^2 = 0 holds on
        every generator of A.natural.

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

Checks three conditions in order.  First, a structural validation: the DG
algebra has keys ring, natural, diff, and Degrees with the right types, and the
length of A.Degrees equals the number of generators of A.natural.  Second,
every generator g of A.natural has d(g) of homological degree |g| - 1.  Third,
d^2(g) = 0 on every generator — Leibniz then extends this to all of A.natural.

When debugLevel > 0 the routine prints a diagnostic line for each failing
check.

+------------------------------------------+
|i1 : R = QQ[x, y, z]                      |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,3  |
|      Differential => {x, y, z}           |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : isWellDefined A                      |
|                                          |
|o3 = true                                 |
+------------------------------------------+

A DG algebra with A.diff == {} (no differential set) passes the check trivially
— the second and third conditions apply only to generators with a stored
differential.

See also
========

  * Well-definedness, acyclicity, and quasi-isomorphism
    -- Predicates that
    check DG-theoretic conditions on DG types
  * DGAlgebra -- The class of all DGAlgebras
  * setDiff -- Install or replace the differential on a DG
    algebra
  * isWellDefined(DGIdeal) -- Verify that a
    DGIdeal has correct structure and is d-closed
  * isAcyclic(DGAlgebra) -- Determine whether a DG algebra
    has no higher homology

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

  * isWellDefined(DGAlgebra) -- Check that
    a DG algebra has correct structure and a differential that squares to zero
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4943:0.

isWellDefined(DGModule) -- Check that a DG module has correct structure and that its differential squares to zero
*****************************************************************************************************************

  * Function: isWellDefined (Macaulay2Doc),
  * Usage:
        b = isWellDefined M
  * Inputs:
      * M, an instance of the type DGModule,
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), True when M has all
        expected structural keys, its base DG algebra M.dgAlgebra is itself
        well-defined, the ring of M matches that of its DG algebra, each stored
        differential is a module element of M.natural, and d_M^2 = 0 on every
        generator.

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

Performs a structural check (required keys and list-length agreement #M.diff ==
#M.Degrees), then verifies that M.dgAlgebra is a well-defined DG algebra,
checks that each entry of M.diff is a vector or matrix over M.natural, and
finally calls the internal isWellDefinedDifferential routine to verify d_M^2 =
0 up to the natural bound.

Diagnostic messages are emitted when debugLevel > 0.

+--------------------------------------------------------+
|i1 : R = ZZ/101[x]                                      |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                    }                    |
|      Underlying algebra => R[T   ]                     |
|                               1,1                      |
|      Differential => {x}                               |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                        |
|                                                        |
|o3 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, 0}                   |
|                                                        |
|o3 : DGModule                                           |
+--------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                        |
|o4 = {| 1 |, | 0 |}                                     |
|      | 0 |  | 1 |                                      |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : setDiff(M, {0, x * natGens#0})                     |
|                                                        |
|o5 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, | x |}               |
|                                   | 0 |                |
|                                                        |
|o5 : DGModule                                           |
+--------------------------------------------------------+
|i6 : isWellDefined M                                    |
|                                                        |
|o6 = true                                               |
+--------------------------------------------------------+

See also
========

  * Well-definedness, acyclicity, and quasi-isomorphism
    -- Predicates that
    check DG-theoretic conditions on DG types
  * DGModule -- The class of DG modules over a DG algebra
  * freeDGModule -- Construct a free DG module over a DG
    algebra
  * setDiff -- Install or replace the differential on a DG
    algebra
  * isWellDefined(DGSubmodule) -- Check
    that a DG submodule is d-closed in its ambient DG module
  * isWellDefined(DGModuleMap) -- Check
    that a DG module map has correct structure and is a chain map

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

  * isWellDefined(DGModule) -- Check that a
    DG module has correct structure and that its differential squares to zero
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:4986:0.

isWellDefined(DGSubmodule) -- Check that a DG submodule is d-closed in its ambient DG module
********************************************************************************************

  * Function: isWellDefined (Macaulay2Doc),
  * Usage:
        b = isWellDefined S
  * Inputs:
      * S, an instance of the type DGSubmodule,
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), True when S has all
        expected structural keys, its ambient is a well-defined DG module, and
        the column span of S.inclusion.natural in S.ambient.natural is stable
        under d_{S.ambient}.

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

After a structural key check, verifies that S.ambient is a well-defined DG
module, then checks d-closure: for every column v of the inclusion matrix,
d_M(v) lies in the column span of the inclusion matrix modulo further columns.
This is the one nontrivial condition that distinguishes a DG submodule from a
general A.natural-submodule of M.natural.

+--------------------------------------------------------+
|i1 : R = ZZ/101[x]                                      |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                    }                    |
|      Underlying algebra => R[T   ]                     |
|                               1,1                      |
|      Differential => {x}                               |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                        |
|                                                        |
|o3 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, 0}                   |
|                                                        |
|o3 : DGModule                                           |
+--------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                        |
|o4 = {| 1 |, | 0 |}                                     |
|      | 0 |  | 1 |                                      |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : setDiff(M, {0, x * natGens#0})                     |
|                                                        |
|o5 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, | x |}               |
|                                   | 0 |                |
|                                                        |
|o5 : DGModule                                           |
+--------------------------------------------------------+
|i6 : S = dgSubmodule(M, (id_(M.natural))_{1})           |
|                                                        |
|o6 = DGSubmodule of ambient DGModule                    |
|     Degrees  => {{1, 0}, {0, 0}}                       |
|                          2                             |
|     natural  => (R[T   ])                              |
|                     1,1                                |
|     inclusion => {0, 0} | 0 x |                        |
|                  {1, 0} | 1 0 |                        |
|                                                        |
|o6 : DGSubmodule                                        |
+--------------------------------------------------------+
|i7 : isWellDefined S                                    |
|                                                        |
|o7 = true                                               |
+--------------------------------------------------------+

See also
========

  * Well-definedness, acyclicity, and quasi-isomorphism
    -- Predicates that
    check DG-theoretic conditions on DG types
  * DGSubmodule -- The class of d-closed submodules of a DG
    module
  * dgSubmodule -- Construct a d-closed submodule of a DG
    module
  * isWellDefined(DGModule) -- Check that a
    DG module has correct structure and that its differential squares to zero
  * isWellDefined(DGQuotientModule),
    -- Check that a DG quotient module has a well-defined differential

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

  * isWellDefined(DGSubmodule) -- Check
    that a DG submodule is d-closed in its ambient DG module
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5026:0.

isWellDefined(DGQuotientModule) -- Check that a DG quotient module has a well-defined differential
**************************************************************************************************

  * Function: isWellDefined (Macaulay2Doc),
  * Usage:
        b = isWellDefined Q
  * Inputs:
      * Q, an instance of the type DGQuotientModule,
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), True when Q has all
        expected structural keys, its projection map has the right source and
        target, and its relations submodule Q.subDGModule is itself a
        well-defined DG submodule of Q.ambient.

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

After a structural key-shape check, verifies that Q.ambient is a
DGModule, that Q.subDGModule is a DGSubmodule,
with ambient equal to Q.ambient, and that Q.projection is a DGModuleMap,
from Q.ambient to Q. The substantive check then delegates to
isWellDefined(DGSubmodule), on the relations
submodule: the quotient is well-defined exactly when the relations are d-closed
in the ambient.

+--------------------------------------------------------+
|i1 : R = ZZ/101[x]                                      |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                    }                    |
|      Underlying algebra => R[T   ]                     |
|                               1,1                      |
|      Differential => {x}                               |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                        |
|                                                        |
|o3 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, 0}                   |
|                                                        |
|o3 : DGModule                                           |
+--------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                        |
|o4 = {| 1 |, | 0 |}                                     |
|      | 0 |  | 1 |                                      |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : setDiff(M, {0, x * natGens#0})                     |
|                                                        |
|o5 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, | x |}               |
|                                   | 0 |                |
|                                                        |
|o5 : DGModule                                           |
+--------------------------------------------------------+
|i6 : S = dgSubmodule(M, (id_(M.natural))_{1})           |
|                                                        |
|o6 = DGSubmodule of ambient DGModule                    |
|     Degrees  => {{1, 0}, {0, 0}}                       |
|                          2                             |
|     natural  => (R[T   ])                              |
|                     1,1                                |
|     inclusion => {0, 0} | 0 x |                        |
|                  {1, 0} | 1 0 |                        |
|                                                        |
|o6 : DGSubmodule                                        |
+--------------------------------------------------------+
|i7 : Q = M / S                                          |
|                                                        |
|o7 = DGQuotientModule Q = M / S                         |
|     Q.natural = cokernel {0, 0} | 0 x |                |
|                          {1, 0} | 1 0 |                |
|     Degrees   = {{0, 0}, {1, 0}}                       |
|                                                        |
|o7 : DGQuotientModule                                   |
+--------------------------------------------------------+
|i8 : isWellDefined Q                                    |
|                                                        |
|o8 = true                                               |
+--------------------------------------------------------+

See also
========

  * Well-definedness, acyclicity, and quasi-isomorphism
    -- Predicates that
    check DG-theoretic conditions on DG types
  * DGQuotientModule -- The class of quotient DG
    modules M / S
  * dgQuotientModule -- Construct the quotient DG
    module M / S
  * isWellDefined(DGSubmodule) -- Check
    that a DG submodule is d-closed in its ambient DG module
  * DGModule / DGSubmodule -- Quotient DG
    module: M / S

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

  * isWellDefined(DGQuotientModule),
    -- Check that a DG quotient module has a well-defined differential
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5069:0.

isWellDefined(DGModuleMap) -- Check that a DG module map has correct structure and is a chain map
*************************************************************************************************

  * Function: isWellDefined (Macaulay2Doc),
  * Usage:
        b = isWellDefined f
  * Inputs:
      * f, an instance of the type DGModuleMap,
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), True when f has all
        expected structural keys, source and target are DG modules (or DG
        quotient modules) over a common DG algebra, the natural matrix has the
        correct source and target, f preserves hom-degree, and d_N(f(e_i)) =
        f(d_M(e_i)) on every natural generator e_i of the source.

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

Six checks in order: structural key shape; source and target types are
DGModule, or DGQuotientModule,; source and
target share the same DG algebra; f.natural is a module map with the correct
source and target; the hom-degree of f is zero; and the chain-map condition
holds on every generator of the source.

Modeled on isWellDefined ComplexMap from the Complexes package.  Diagnostic
messages are emitted when debugLevel > 0.

+------------------------------------------------------------------------+
|i1 : R = QQ[x, y]/ideal(x^2, y^2)                                       |
|                                                                        |
|o1 = R                                                                  |
|                                                                        |
|o1 : QuotientRing                                                       |
+------------------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                             |
|                                                                        |
|o2 = {Ring => R                          }                              |
|      Underlying algebra => R[T   ..T   ]                               |
|                               1,1   1,2                                |
|      Differential => {x, y}                                            |
|                                                                        |
|o2 : DGAlgebra                                                          |
+------------------------------------------------------------------------+
|i3 : M = minimalSemifreeResolution(A, R^1 / ideal(x, y), EndDegree => 2)|
|                                                                        |
|o3 = {Base ring => R                                          }         |
|      DG algebra => R[T   ..T   ]                                       |
|                       1,1   1,2                                        |
|                                       3                                |
|      Natural module => (R[T   ..T   ])                                 |
|                            1,1   1,2                                   |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}}                     |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |}          |
|                                   |     0    |  |     0    |           |
|                                   |     0    |  |     0    |           |
|                                                                        |
|o3 : DGModule                                                           |
+------------------------------------------------------------------------+
|i4 : idM = identityDGModuleMap M                                        |
|                                                                        |
|                               3                                        |
|o4 = {Source => (R[T   ..T   ])  }                                      |
|                    1,1   1,2                                           |
|                               3                                        |
|      Target => (R[T   ..T   ])                                         |
|                    1,1   1,2                                           |
|      Natural => {0, 0} | 1 0 0 |                                       |
|                 {2, 2} | 0 1 0 |                                       |
|                 {2, 2} | 0 0 1 |                                       |
|                                                                        |
|o4 : DGModuleMap                                                        |
+------------------------------------------------------------------------+
|i5 : zM = zeroDGModuleMap(M, M)                                         |
|                                                                        |
|                               3                                        |
|o5 = {Source => (R[T   ..T   ]) }                                       |
|                    1,1   1,2                                           |
|                               3                                        |
|      Target => (R[T   ..T   ])                                         |
|                    1,1   1,2                                           |
|      Natural => 0                                                      |
|                                                                        |
|o5 : DGModuleMap                                                        |
+------------------------------------------------------------------------+
|i6 : isWellDefined idM                                                  |
|                                                                        |
|o6 = true                                                               |
+------------------------------------------------------------------------+
|i7 : isWellDefined zM                                                   |
|                                                                        |
|o7 = true                                                               |
+------------------------------------------------------------------------+

See also
========

  * Well-definedness, acyclicity, and quasi-isomorphism
    -- Predicates that
    check DG-theoretic conditions on DG types
  * DGModuleMap -- The class of morphisms of DG modules
    over a common DG algebra
  * dgModuleMap -- Construct a DGModuleMap from a matrix or
    from a list of image Vectors
  * identityDGModuleMap -- The identity DGModuleMap
    on a DG module
  * zeroDGModuleMap -- The zero DGModuleMap between two
    DG modules over a common algebra
  * isWellDefined(DGModule) -- Check that a
    DG module has correct structure and that its differential squares to zero

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

  * isWellDefined(DGModuleMap) -- Check
    that a DG module map has correct structure and is a chain map
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5115:0.

isAcyclic(DGModule) -- Determine whether a DG module has vanishing positive-degree homology
*******************************************************************************************

  * Function: isAcyclic,
  * Usage:
        b = isAcyclic M
        b = isAcyclic(M, EndDegree => n)
  * Inputs:
      * M, an instance of the type DGModule,
  * Optional inputs (Macaulay2Doc),:
      * EndDegree, => an
        integer (Macaulay2Doc), default value -1, An upper bound for
        the range of degrees checked.  Required when M has infinite
        maxDegree, (for example, when its DG algebra is an
        acyclicClosure).  When omitted and M is
        finite-dimensional, maxDegree M is used.
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), True when H_i(M) = 0
        for all 1 <= i <= n.

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

Checks per-degree homology via HH_ZZ DGModule, and
prune (Macaulay2Doc).  Degree zero is intentionally excluded:
acyclicity concerns only positive-degree homology.

+------------------------------------------+
|i1 : R = QQ[x, y, z]                      |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,3  |
|      Differential => {x, y, z}           |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : KM = koszulComplexDGM R^1            |
|                                          |
|o3 = {Base ring => R                    } |
|      DG algebra => R[T   ..T   ]         |
|                       1,1   1,3          |
|                                       1  |
|      Natural module => (R[T   ..T   ])   |
|                            1,1   1,3     |
|      Generator degrees => {{0, 0}}       |
|      Differentials on gens => {0}        |
|                                          |
|o3 : DGModule                             |
+------------------------------------------+
|i4 : isAcyclic KM                         |
|                                          |
|o4 = true                                 |
+------------------------------------------+

For the Koszul DG module on a regular sequence, all positive-degree homology
vanishes (H_0 = R / (x, y, z) is the only nonzero piece).

+------------------------------------------+
|i5 : R' = QQ[x, y]/ideal(x^2, y^2)        |
|                                          |
|o5 = R'                                   |
|                                          |
|o5 : QuotientRing                         |
+------------------------------------------+
|i6 : KM' = koszulComplexDGM R'^1          |
|                                          |
|o6 = {Base ring => R'                    }|
|      DG algebra => R'[T   ..T   ]        |
|                        1,1   1,2         |
|                                        1 |
|      Natural module => (R'[T   ..T   ])  |
|                             1,1   1,2    |
|      Generator degrees => {{0, 0}}       |
|      Differentials on gens => {0}        |
|                                          |
|o6 : DGModule                             |
+------------------------------------------+
|i7 : not isAcyclic(KM', EndDegree => 3)   |
|                                          |
|o7 = true                                 |
+------------------------------------------+

Over a non-regular ring the Koszul DG module picks up nontrivial
positive-degree homology.

See also
========

  * Well-definedness, acyclicity, and quasi-isomorphism
    -- Predicates that
    check DG-theoretic conditions on DG types
  * isAcyclic(DGAlgebra) -- Determine whether a DG algebra
    has no higher homology
  * isAcyclic(DGQuotientModule), --
    Determine whether a DG quotient module has vanishing positive-degree
    homology
  * HH_ZZ DGModule -- The degree-n homology of a DG
    module as a module over the base ring
  * EndDegree -- Option to specify the last homological
    degree processed by an iterative DG construction

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

  * isAcyclic(DGModule) -- Determine whether a
    DG module has vanishing positive-degree homology
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5163:0.

isAcyclic(DGQuotientModule) -- Determine whether a DG quotient module has vanishing positive-degree homology
************************************************************************************************************

  * Function: isAcyclic,
  * Usage:
        b = isAcyclic Q
        b = isAcyclic(Q, EndDegree => n)
  * Inputs:
      * Q, an instance of the type DGQuotientModule,
  * Optional inputs (Macaulay2Doc),:
      * EndDegree, => an
        integer (Macaulay2Doc), default value -1, An upper bound for
        the range of degrees checked.  Required when Q.ambient has infinite
        maxDegree.
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), True when H_i(Q) = 0
        for all 1 <= i <= n.

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

Semantics match isAcyclic(DGModule),:
positive-degree homology only, computed via HH_ZZ DGQuotientModule,
and prune (Macaulay2Doc).

+--------------------------------------------------------+
|i1 : R = ZZ/101[x]                                      |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                    }                    |
|      Underlying algebra => R[T   ]                     |
|                               1,1                      |
|      Differential => {x}                               |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                        |
|                                                        |
|o3 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, 0}                   |
|                                                        |
|o3 : DGModule                                           |
+--------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                        |
|o4 = {| 1 |, | 0 |}                                     |
|      | 0 |  | 1 |                                      |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : setDiff(M, {0, x * natGens#0})                     |
|                                                        |
|o5 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, | x |}               |
|                                   | 0 |                |
|                                                        |
|o5 : DGModule                                           |
+--------------------------------------------------------+
|i6 : Sfull = dgSubmodule(M, id_(M.natural))             |
|                                                        |
|o6 = DGSubmodule of ambient DGModule                    |
|     Degrees  => {{0, 0}, {1, 0}}                       |
|                          2                             |
|     natural  => (R[T   ])                              |
|                     1,1                                |
|     inclusion => {0, 0} | 1 0 |                        |
|                  {1, 0} | 0 1 |                        |
|                                                        |
|o6 : DGSubmodule                                        |
+--------------------------------------------------------+
|i7 : Q0 = M / Sfull                                     |
|                                                        |
|o7 = DGQuotientModule Q = M / S                         |
|     Q.natural = cokernel {0, 0} | 1 0 |                |
|                          {1, 0} | 0 1 |                |
|     Degrees   = {{0, 0}, {1, 0}}                       |
|                                                        |
|o7 : DGQuotientModule                                   |
+--------------------------------------------------------+
|i8 : isAcyclic Q0                                       |
|                                                        |
|o8 = true                                               |
+--------------------------------------------------------+

When the quotient is the zero DG module, isAcyclic holds trivially.

See also
========

  * Well-definedness, acyclicity, and quasi-isomorphism
    -- Predicates that
    check DG-theoretic conditions on DG types
  * isAcyclic(DGModule) -- Determine whether a
    DG module has vanishing positive-degree homology
  * HH_ZZ DGQuotientModule -- The degree-n
    homology of a DG quotient module
  * EndDegree -- Option to specify the last homological
    degree processed by an iterative DG construction

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

  * isAcyclic(DGQuotientModule), --
    Determine whether a DG quotient module has vanishing positive-degree
    homology
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5204:0.

isQuasiIsomorphism(DGAlgebraMap) -- Determine whether a DG algebra map induces an isomorphism on homology
*********************************************************************************************************

  * Function: isQuasiIsomorphism (Complexes),
  * Usage:
        b = isQuasiIsomorphism phi
  * Inputs:
      * phi, an instance of the type DGAlgebraMap,
  * Optional inputs (Macaulay2Doc),:
      * Concentration (Complexes), =>
        ..., default value (-infinity,infinity),
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), True when the induced
        chain map toComplexMap phi is a quasi-isomorphism on the underlying
        complexes.

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

Computed by forwarding to isQuasiIsomorphism(toComplexMap phi) from the
Complexes package.  The underlying check inspects H_n of the induced chain map
at every degree in the concentration of the source and target.  The
Concentration option of the Complexes version is accepted and passed through.

+--------------------------------------------------------------------+
|i1 : R = QQ[x, y, z]                                                |
|                                                                    |
|o1 = R                                                              |
|                                                                    |
|o1 : PolynomialRing                                                 |
+--------------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                         |
|                                                                    |
|o2 = {Ring => R                          }                          |
|      Underlying algebra => R[T   ..T   ]                           |
|                               1,1   1,3                            |
|      Differential => {x, y, z}                                     |
|                                                                    |
|o2 : DGAlgebra                                                      |
+--------------------------------------------------------------------+
|i3 : phi = identityDGAlgebraMap A                                   |
|                                                                    |
|o3 = map (R[T   ..T   ], R[T   ..T   ], {T   , T   , T   , x, y, z})|
|             1,1   1,3      1,1   1,3     1,1   1,2   1,3           |
|                                                                    |
|o3 : DGAlgebraMap                                                   |
+--------------------------------------------------------------------+
|i4 : isQuasiIsomorphism phi                                         |
|                                                                    |
|o4 = true                                                           |
+--------------------------------------------------------------------+

The identity DG algebra map is trivially a quasi-isomorphism.

See also
========

  * Well-definedness, acyclicity, and quasi-isomorphism
    -- Predicates that
    check DG-theoretic conditions on DG types
  * isQuasiIsomorphism(DGModuleMap), --
    Elementary predicates and constructors for DGModuleMaps
  * identityDGAlgebraMap -- The identity
    DGAlgebraMap on a DG algebra
  * toComplexMap -- Construct the ComplexMap associated to
    a DGAlgebraMap

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

  * isQuasiIsomorphism(DGAlgebraMap)
    -- Determine whether a DG algebra map
    induces an isomorphism on homology
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5239:0.

annihilator(DGSubmodule) -- The DG ideal of A annihilating a DG submodule
*************************************************************************

  * Function: annihilator (missing documentation)
  * Usage:
        I = annihilator S
  * Inputs:
      * S, an instance of the type DGSubmodule,
  * Optional inputs (Macaulay2Doc),:
      * Strategy (missing documentation) => ..., default value null,
  * Outputs:
      * I, an instance of the type DGIdeal, The DG ideal of
        S.ambient.dgAlgebra whose underlying ideal is the annihilator of image
        S.inclusion.natural as a submodule of S.ambient.natural.

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

Computes annihilator(image S.inclusion.natural) at the A.natural level, then
wraps the result as a DG ideal. The result is a DG ideal: if a annihilates S
and s \in S, then d(a s) = d(a) s \pm a d(s) vanishes because both terms vanish
(the second since d(s) \in S), so d(a) s = 0 for every s \in S and d(a) is
again in the annihilator.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : M = freeDGModule(A, {0})                      |
|                                                   |
|o4 = {Base ring => R               }               |
|      DG algebra => Anat                           |
|                            1                      |
|      Natural module => Anat                       |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o4 : DGModule                                      |
+---------------------------------------------------+
|i5 : S = dgSubmodule(M, matrix {{x_Anat}})         |
|                                                   |
|o5 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => | x |                            |
|                                                   |
|o5 : DGSubmodule                                   |
+---------------------------------------------------+
|i6 : I = annihilator S                             |
|                                                   |
|o6 = DGIdeal of Anat                               |
|     generators => 0                               |
|                                                   |
|o6 : DGIdeal                                       |
+---------------------------------------------------+
|i7 : isWellDefined I                               |
|                                                   |
|o7 = true                                          |
+---------------------------------------------------+

The annihilator of the zero submodule is the unit ideal.

+-----------------------------------------------------+
|i8 : S0 = dgSubmodule(M, map(M.natural, (Anat)^0, 0))|
|                                                     |
|o8 = DGSubmodule of ambient DGModule                 |
|     Degrees  => {}                                  |
|     natural  => 0                                   |
|     inclusion => 0                                  |
|                                                     |
|o8 : DGSubmodule                                     |
+-----------------------------------------------------+
|i9 : annihilator S0 == dgIdeal(A, {1_Anat})          |
|                                                     |
|o9 = true                                            |
+-----------------------------------------------------+

See also
========

  * Well-definedness, acyclicity, and quasi-isomorphism
    -- Predicates that
    check DG-theoretic conditions on DG types
  * annihilator(DGQuotientModule), --
    The DG ideal of A annihilating a DG quotient module
  * DGIdeal -- The class of d-closed graded ideals of a DG
    algebra
  * dgIdeal -- Construct a DG ideal from a list, matrix, or
    ideal of generators
  * DGSubmodule -- The class of d-closed submodules of a DG
    module

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

  * annihilator(DGSubmodule) -- The DG
    ideal of A annihilating a DG submodule
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5284:0.

annihilator(DGQuotientModule) -- The DG ideal of A annihilating a DG quotient module
************************************************************************************

  * Function: annihilator (missing documentation)
  * Usage:
        I = annihilator Q
  * Inputs:
      * Q, an instance of the type DGQuotientModule,
  * Optional inputs (Macaulay2Doc),:
      * Strategy (missing documentation) => ..., default value null,
  * Outputs:
      * I, an instance of the type DGIdeal, The DG ideal of
        Q.dgAlgebra whose underlying ideal is the annihilator of Q.natural (a
        cokernel presentation) as an A.natural-module.

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

Computes annihilator Q.natural and wraps it as a DG ideal.  As with
annihilator(DGSubmodule), the result is
automatically d-closed: the argument showing closure uses Leibniz together with
the fact that d on the ambient descends to d on the quotient.

+---------------------------------------------------+
|i1 : R = ZZ/101[x, y]                              |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : Anat = A.natural                              |
|                                                   |
|o3 = Anat                                          |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : M = freeDGModule(A, {0})                      |
|                                                   |
|o4 = {Base ring => R               }               |
|      DG algebra => Anat                           |
|                            1                      |
|      Natural module => Anat                       |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o4 : DGModule                                      |
+---------------------------------------------------+
|i5 : S = dgSubmodule(M, matrix {{x_Anat}})         |
|                                                   |
|o5 = DGSubmodule of ambient DGModule               |
|     Degrees  => {{0, 1}}                          |
|                     1                             |
|     natural  => Anat                              |
|     inclusion => | x |                            |
|                                                   |
|o5 : DGSubmodule                                   |
+---------------------------------------------------+
|i6 : Q = M / S                                     |
|                                                   |
|o6 = DGQuotientModule Q = M / S                    |
|     Q.natural = cokernel | x |                    |
|     Degrees   = {{0, 0}}                          |
|                                                   |
|o6 : DGQuotientModule                              |
+---------------------------------------------------+
|i7 : I = annihilator Q                             |
|                                                   |
|o7 = DGIdeal of Anat                               |
|     generators => | x |                           |
|                                                   |
|o7 : DGIdeal                                       |
+---------------------------------------------------+
|i8 : isWellDefined I                               |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+
|i9 : isSubset(dgIdeal(A, {x_Anat}), I)             |
|                                                   |
|o9 = true                                          |
+---------------------------------------------------+

See also
========

  * Well-definedness, acyclicity, and quasi-isomorphism
    -- Predicates that
    check DG-theoretic conditions on DG types
  * annihilator(DGSubmodule) -- The DG
    ideal of A annihilating a DG submodule
  * DGIdeal -- The class of d-closed graded ideals of a DG
    algebra
  * dgQuotientModule -- Construct the quotient DG
    module M / S
  * DGQuotientModule -- The class of quotient DG
    modules M / S

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

  * annihilator(DGQuotientModule), --
    The DG ideal of A annihilating a DG quotient module
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5323:0.

Semifree resolutions of DG modules -- Building semifree DG module resolutions via koszulComplexDGM, adjoinGenerators, killCycles, and semifreeResolution
********************************************************************************************************************************************************

A DGModule, F over a DGAlgebra, A is semifree
if its underlying graded A.natural-module is free with a homogeneous basis.
Semifree DG modules play the role of free modules in ordinary homological
algebra: every A-module (or A.ring-module lifted along the augmentation A ->
A.ring) admits a semifree resolution, unique up to DG module homotopy.

The package provides four building blocks for assembling semifree resolutions
by hand or automatically:

koszulComplexDGM, constructs the Koszul DG module K^R
\otimes_R M as a DG module over koszulComplexDGA(ring M).  On a regular ring
this is already a free resolution of M; over a singular ring it provides a
starting point that needs further generators adjoined to kill higher homology.

See adjoinGenerators, takes a free DG module M and a list
of cycles in M.natural and returns a new free DG module with one additional
generator per cycle, whose differential is that cycle.  This is the
module-theoretic analog of adjoinVariables, on a DG
algebra.

See killCycles(DGModule), scans for the smallest
hom-degree n in the requested range at which H_n(M) is nonzero, then adjoins
one new hom-degree-(n+1) generator per minimal homology class.  Iterating this
from StartDegree up to EndDegree produces a DG module with vanishing homology
in that range.

See semifreeResolution, automates the full construction:
build a free cover of M, adjoin hom-degree-1 generators for the relations of M,
then iterate killCycles(DGModule).  Its
refined cousin minimalSemifreeResolution,
applies getBoundaryPreimage, at each stage to
subtract off boundaries before adjoining, producing a resolution that is
minimal over A in the sense that every generator's differential lands in the
augmentation ideal of A.natural.  The predicate
isMinimalSemifreeResolution, tests this minimality
condition.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)                                          |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : k = R^1 / ideal(x, y)                                                   |
|                                                                             |
|o2 = cokernel | x y |                                                        |
|                                                                             |
|                            1                                                |
|o2 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+
|i3 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o3 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,2                                     |
|      Differential => {x, y}                                                 |
|                                                                             |
|o3 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i4 : Mdg = minimalSemifreeResolution(A, k, EndDegree => 3)                   |
|                                                                             |
|o4 = {Base ring => R                                                         |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       6                                     |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}, {4, 4}, {4, 4}, {4, 4}}  |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |, |     0    |, |
|                                   |     0    |  |     0    |  | xT_(1,1) |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                                                             |
|o4 : DGModule                                                                |
|-----------------------------------------------------------------------------|
|                           }                                                 |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
||     0    |, |     0    |}                                                  |
|| yT_(1,2) |  |     0    |                                                   |
|| xT_(1,1) |  | yT_(1,2) |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
+-----------------------------------------------------------------------------+
|i5 : isMinimalSemifreeResolution Mdg                                         |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+
|i6 : apply(0..3, n -> prune homology(n, Mdg))                                |
|                                                                             |
|o6 = (cokernel | y x |, 0, 0, 0)                                             |
|                                                                             |
|o6 : Sequence                                                                |
+-----------------------------------------------------------------------------+

Over a complete intersection of codimension two, the rank of F_n in the minimal
semifree resolution of the residue field matches the n-th Betti number n+1, as
expected from the Tate construction.

See also
========

  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension
  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree
  * adjoinVariables -- Extend a DG algebra by a
    user-chosen list of cycles to be killed
  * getBoundaryPreimage -- Attempt to find a
    preimage of a boundary under the differential of a DGAlgebra.

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5403:0.

koszulComplexDGM -- The Koszul complex of a module as a DG module
*****************************************************************

  * Usage:
        KM = koszulComplexDGM M
        KM = koszulComplexDGM(A, M)
  * Inputs:
      * A, an instance of the type DGAlgebra, A DG algebra
        over R = ring M.  If omitted, koszulComplexDGA(ring M) is used.
      * M, a module (Macaulay2Doc), A module over a polynomial or
        quotient ring R.
  * Outputs:
      * KM, an instance of the type DGModule, The Koszul DG
        module K^R \otimes_R M viewed as a DG module over A.

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

The module generators of KM are one copy of each generator of M, placed in
hom-degree 0.  The differential vanishes on these generators, so the full
differential of KM is determined by the Leibniz rule together with the
differential on A.natural.  In the one-argument form the DG algebra is built on
demand via koszulComplexDGA(ring M); in the two-argument form the caller
supplies A, whose ring must equal ring M.

On a regular ring R, K^R resolves the residue field k, so koszulComplexDGM M
resolves M via k \otimes_R M-style homology.  In particular koszulComplexDGM
R^1 recovers the Koszul complex of R itself.

Over a regular ring, the Koszul DG module on R^1 is a free resolution of the
residue field, so its higher homology vanishes:

+--------------------------------------------+
|i1 : R = QQ[x, y, z]                        |
|                                            |
|o1 = R                                      |
|                                            |
|o1 : PolynomialRing                         |
+--------------------------------------------+
|i2 : KM = koszulComplexDGM R^1              |
|                                            |
|o2 = {Base ring => R                    }   |
|      DG algebra => R[T   ..T   ]           |
|                       1,1   1,3            |
|                                       1    |
|      Natural module => (R[T   ..T   ])     |
|                            1,1   1,3       |
|      Generator degrees => {{0, 0}}         |
|      Differentials on gens => {0}          |
|                                            |
|o2 : DGModule                               |
+--------------------------------------------+
|i3 : apply(0..3, n -> prune homology(n, KM))|
|                                            |
|o3 = (cokernel | z y x |, 0, 0, 0)          |
|                                            |
|o3 : Sequence                               |
+--------------------------------------------+

Over a complete intersection, the higher homology of koszulComplexDGM R^1 is no
longer zero — it is the Koszul homology algebra of R, which records the
deviations of R.  For the codimension-2 complete intersection k[x,y]/(x^2,
y^2), HH_i(KM) has rank equal to the i-th Betti number of the residue field:

+----------------------------------------------------+
|i4 : S = QQ[x, y] / ideal(x^2, y^2)                 |
|                                                    |
|o4 = S                                              |
|                                                    |
|o4 : QuotientRing                                   |
+----------------------------------------------------+
|i5 : KS = koszulComplexDGM S^1                      |
|                                                    |
|o5 = {Base ring => S                    }           |
|      DG algebra => S[T   ..T   ]                   |
|                       1,1   1,2                    |
|                                       1            |
|      Natural module => (S[T   ..T   ])             |
|                            1,1   1,2               |
|      Generator degrees => {{0, 0}}                 |
|      Differentials on gens => {0}                  |
|                                                    |
|o5 : DGModule                                       |
+----------------------------------------------------+
|i6 : apply(0..3, n -> numgens prune homology(n, KS))|
|                                                    |
|o6 = (1, 2, 1, 0)                                   |
|                                                    |
|o6 : Sequence                                       |
+----------------------------------------------------+

Applying koszulComplexDGM, to a nontrivial quotient
module produces its Koszul resolution, now tensored against the given module.
Here we resolve S / (x) over S = k[x, y] and read off its free ranks:

+-------------------------------------------------------------------+
|i7 : S = QQ[x, y]                                                  |
|                                                                   |
|o7 = S                                                             |
|                                                                   |
|o7 : PolynomialRing                                                |
+-------------------------------------------------------------------+
|i8 : KQ = koszulComplexDGM(S^1 / ideal(x))                         |
|                                                                   |
|o8 = {Base ring => S                  }                            |
|      DG algebra => S[T   ..T   ]                                  |
|                       1,1   1,2                                   |
|      Natural module => cokernel | x |                             |
|      Generator degrees => {{0, 0}}                                |
|      Differentials on gens => {0}                                 |
|                                                                   |
|o8 : DGModule                                                      |
+-------------------------------------------------------------------+
|i9 : C = toComplex KQ                                              |
|                                                                   |
|o9 = cokernel | x | <-- cokernel {1} | x 0 | <-- cokernel {2} | x ||
|                                 {1} | 0 x |                       |
|     0                                           2                 |
|                        1                                          |
|                                                                   |
|o9 : Complex                                                       |
+-------------------------------------------------------------------+
|i10 : apply(0..2, n -> rank C_n)                                   |
|                                                                   |
|o10 = (0, 0, 0)                                                    |
|                                                                   |
|o10 : Sequence                                                     |
+-------------------------------------------------------------------+
|i11 : apply(0..2, n -> prune homology(n, KQ))                      |
|                                                                   |
|o11 = (cokernel | y x |, cokernel {1} | y x |, 0)                  |
|                                                                   |
|o11 : Sequence                                                     |
+-------------------------------------------------------------------+

In the two-argument form the caller-supplied DG algebra must share the base
ring of the module.  This is the usual way to build a Koszul DG module that
lives over the DGAlgebra, you will pass to
semifreeResolution, or minimalSemifreeResolution,:

+-----------------------------------------------------------------------------+
|i12 : R = QQ[x, y] / ideal(x^2, y^2)                                         |
|                                                                             |
|o12 = R                                                                      |
|                                                                             |
|o12 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i13 : A = koszulComplexDGA R                                                 |
|                                                                             |
|o13 = {Ring => R                          }                                  |
|       Underlying algebra => R[T   ..T   ]                                   |
|                                1,1   1,2                                    |
|       Differential => {x, y}                                                |
|                                                                             |
|o13 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i14 : Mdg = minimalSemifreeResolution(A, R^1 / ideal(x, y), EndDegree => 3)  |
|                                                                             |
|o14 = {Base ring => R                                                        |
|       DG algebra => R[T   ..T   ]                                           |
|                        1,1   1,2                                            |
|                                        6                                    |
|       Natural module => (R[T   ..T   ])                                     |
|                             1,1   1,2                                       |
|       Generator degrees => {{0, 0}, {2, 2}, {2, 2}, {4, 4}, {4, 4}, {4, 4}} |
|       Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |, |     0    |,|
|                                    |     0    |  |     0    |  | xT_(1,1) | |
|                                    |     0    |  |     0    |  |     0    | |
|                                    |     0    |  |     0    |  |     0    | |
|                                    |     0    |  |     0    |  |     0    | |
|                                    |     0    |  |     0    |  |     0    | |
|                                                                             |
|o14 : DGModule                                                               |
|-----------------------------------------------------------------------------|
|                           }                                                 |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
||     0    |, |     0    |}                                                  |
|| yT_(1,2) |  |     0    |                                                   |
|| xT_(1,1) |  | yT_(1,2) |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
+-----------------------------------------------------------------------------+
|i15 : apply(0..3, n -> rank (toComplex Mdg)_n)                               |
|                                                                             |
|o15 = (1, 2, 3, 4)                                                           |
|                                                                             |
|o15 : Sequence                                                               |
+-----------------------------------------------------------------------------+

Caveat
======

The two-argument form raises an error when A.ring =!= ring M.

See also
========

  * Semifree resolutions of DG modules
    -- Building semifree DG module resolutions via koszulComplexDGM,
    adjoinGenerators, killCycles, and semifreeResolution
  * koszulComplexDGA -- The Koszul complex on the
    variables of a ring, as a DG algebra
  * DGModule -- The class of DG modules over a DG algebra
  * freeDGModule -- Construct a free DG module over a DG
    algebra
  * semifreeResolution -- Build a semifree DG module
    resolving a module over the base ring
  * minimalSemifreeResolution -- Build a
    minimal semifree DG module resolution over a DG algebra

Ways to use koszulComplexDGM:
=============================

  * "koszulComplexDGM(DGAlgebra,Module)"
  * "koszulComplexDGM(Module)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5492:0.

adjoinGenerators -- Adjoin new free generators to a DG module with prescribed differentials
*******************************************************************************************

  * Usage:
        Mnew = adjoinGenerators(M, cycleList)
  * Inputs:
      * M, an instance of the type DGModule, A free DG module
        (built by freeDGModule, or an earlier call to
        adjoinGenerators).
      * cycleList, a list (Macaulay2Doc), A list of Vectors in
        M.natural; each entry should be a cycle under the differential of M,
        homogeneous with respect to the ambient multi-grading.
  * Outputs:
      * Mnew, an instance of the type DGModule, A free DG
        module whose generator list is M.Degrees followed by one new generator
        per cycle in cycleList, shifted up by one hom-degree, with differential
        equal to the corresponding cycle.

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

This is the module-theoretic analog of adjoinVariables,
on a DG algebra.  For each z in cycleList of hom-degree d, the output has a
fresh generator in hom-degree d + 1 whose differential is z.  If z is indeed a
cycle then the new generator witnesses its homology class as a boundary, so
homology classes supported on cycleList are killed.

Existing generator indices and their differentials are preserved verbatim: the
first #M.Degrees generators of Mnew correspond to those of M, so code that
references (M.natural)_i for old indices i continues to work when lifted to
Mnew.

+--------------------------------------------------------+
|i1 : R = QQ[x]                                          |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                    }                    |
|      Underlying algebra => R[T   ]                     |
|                               1,1                      |
|      Differential => {x}                               |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : M = freeDGModule(A, {0})                           |
|                                                        |
|o3 = {Base ring => R               }                    |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 1                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}}                     |
|      Differentials on gens => {0}                      |
|                                                        |
|o3 : DGModule                                           |
+--------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                        |
|o4 = {| 1 |}                                            |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : Mnew = adjoinGenerators(M, {x * natGens#0})        |
|                                                        |
|o5 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 1}}             |
|      Differentials on gens => {0, | x |}               |
|                                   | 0 |                |
|                                                        |
|o5 : DGModule                                           |
+--------------------------------------------------------+
|i6 : #Mnew.Degrees                                      |
|                                                        |
|o6 = 2                                                  |
+--------------------------------------------------------+
|i7 : first Mnew.Degrees#1                               |
|                                                        |
|o7 = 1                                                  |
+--------------------------------------------------------+

The new generator sits in hom-degree 1 and its differential is the cycle x *
e_0 in M.natural.

Caveat
======

Only supported when M.natural is a free A.natural-module (i.e. M was built by
freeDGModule, or a previous adjoinGenerators,
call). Each entry of cycleList must be a cycle; otherwise the
output differential will not satisfy d^2 = 0.

See also
========

  * Semifree resolutions of DG modules
    -- Building semifree DG module resolutions via koszulComplexDGM,
    adjoinGenerators, killCycles, and semifreeResolution
  * freeDGModule -- Construct a free DG module over a DG
    algebra
  * killCycles(DGModule) -- Adjoin free
    generators to kill the lowest nonvanishing homology of a DG module
  * adjoinVariables -- Extend a DG algebra by a
    user-chosen list of cycles to be killed

Ways to use adjoinGenerators:
=============================

  * "adjoinGenerators(DGModule,List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5553:0.

killCycles(DGModule) -- Adjoin free generators to kill the lowest nonvanishing homology of a DG module
******************************************************************************************************

  * Function: killCycles,
  * Usage:
        Mnew = killCycles M
        Mnew = killCycles(M, StartDegree => s, EndDegree => e)
  * Inputs:
      * M, an instance of the type DGModule, A free DG module.
  * Optional inputs (Macaulay2Doc),:
      * StartDegree,
        => an integer (Macaulay2Doc), default value 1, The smallest
        hom-degree at which to look for nontrivial homology. Defaults to 1.
      * EndDegree, =>
        an integer (Macaulay2Doc), default value -1, The largest
        hom-degree at which to look; defaults to StartDegree (so by default a
        single degree is scanned).
      * Variable, =>
        ..., default value null, Option to name the DG algebra generators
        adjoined by killCycles
  * Outputs:
      * Mnew, an instance of the type DGModule, Either M
        itself (if homology vanishes throughout the requested range) or a free
        DG module with additional hom-degree n+1 generators, where n is the
        smallest degree in the range with H_n(M) != 0; the new generators'
        differentials are representative cycles of a minimal generating set for
        H_n(M).

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

The construction mirrors killCycles(DGAlgebra), for DG
modules.  Scanning from StartDegree upwards, the method computes prune
homology(n, M) until it finds the first degree n with nontrivial homology.  It
then lifts the minimal homology generators provided by the pruning map back to
cycles in M_n and hands them to adjoinGenerators,
producing a new DG module in which those classes become boundaries.

A single call kills homology at one degree.  Iterating with successive
StartDegree values is how semifreeResolution, and
minimalSemifreeResolution, build resolutions.

+----------------------------------------------------------+
|i1 : R = QQ[x]                                            |
|                                                          |
|o1 = R                                                    |
|                                                          |
|o1 : PolynomialRing                                       |
+----------------------------------------------------------+
|i2 : A = koszulComplexDGA R                               |
|                                                          |
|o2 = {Ring => R                    }                      |
|      Underlying algebra => R[T   ]                       |
|                               1,1                        |
|      Differential => {x}                                 |
|                                                          |
|o2 : DGAlgebra                                            |
+----------------------------------------------------------+
|i3 : M = freeDGModule(A, {0})                             |
|                                                          |
|o3 = {Base ring => R               }                      |
|      DG algebra => R[T   ]                               |
|                       1,1                                |
|                                 1                        |
|      Natural module => (R[T   ])                         |
|                            1,1                           |
|      Generator degrees => {{0, 0}}                       |
|      Differentials on gens => {0}                        |
|                                                          |
|o3 : DGModule                                             |
+----------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)  |
|                                                          |
|o4 = {| 1 |}                                              |
|                                                          |
|o4 : List                                                 |
+----------------------------------------------------------+
|i5 : M2 = adjoinGenerators(M, {x * natGens#0})            |
|                                                          |
|o5 = {Base ring => R                       }              |
|      DG algebra => R[T   ]                               |
|                       1,1                                |
|                                 2                        |
|      Natural module => (R[T   ])                         |
|                            1,1                           |
|      Generator degrees => {{0, 0}, {1, 1}}               |
|      Differentials on gens => {0, | x |}                 |
|                                   | 0 |                  |
|                                                          |
|o5 : DGModule                                             |
+----------------------------------------------------------+
|i6 : prune homology(0, M2)                                |
|                                                          |
|o6 = cokernel | x |                                       |
|                                                          |
|                            1                             |
|o6 : R-module, quotient of R                              |
+----------------------------------------------------------+
|i7 : M3 = killCycles(M2, StartDegree => 1, EndDegree => 2)|
|                                                          |
|o7 = {Base ring => R                                   }  |
|      DG algebra => R[T   ]                               |
|                       1,1                                |
|                                 3                        |
|      Natural module => (R[T   ])                         |
|                            1,1                           |
|      Generator degrees => {{0, 0}, {1, 1}, {2, 1}}       |
|      Differentials on gens => {0, | x |, | -T_(1,1) |}   |
|                                   | 0 |  |     1    |    |
|                                   | 0 |  |     0    |    |
|                                                          |
|o7 : DGModule                                             |
+----------------------------------------------------------+
|i8 : prune homology(1, M3) == 0                           |
|                                                          |
|o8 = true                                                 |
+----------------------------------------------------------+

M2 has H_0 = R/(x) = k and no higher homology to kill, so M3 agrees with M2 in
this example. In settings where H_1 is nontrivial, killCycles adjoins one
hom-degree-2 generator per minimal H_1 class.

Caveat
======

Raises an error when StartDegree > EndDegree.  The input must be a free DG
module for the underlying homology computation to extract representative
cycles.

See also
========

  * Semifree resolutions of DG modules
    -- Building semifree DG module resolutions via koszulComplexDGM,
    adjoinGenerators, killCycles, and semifreeResolution
  * adjoinGenerators -- Adjoin new free generators to
    a DG module with prescribed differentials
  * killCycles(DGAlgebra) -- Adjoin variables to kill
    non-bounding cycles in the lowest positive degree
  * semifreeResolution -- Build a semifree DG module
    resolving a module over the base ring
  * minimalSemifreeResolution -- Build a
    minimal semifree DG module resolution over a DG algebra
  * StartDegree -- Option to specify the first homological
    degree processed by an iterative DG construction
  * EndDegree -- Option to specify the last homological
    degree processed by an iterative DG construction

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

  * killCycles(DGModule) -- Adjoin free
    generators to kill the lowest nonvanishing homology of a DG module
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5624:0.

semifreeResolution -- Build a semifree DG module resolving a module over the base ring
**************************************************************************************

  * Usage:
        F = semifreeResolution M
        F = semifreeResolution(A, M)
        F = semifreeResolution(A, M, EndDegree => n)
  * Inputs:
      * A, an instance of the type DGAlgebra, A DG algebra
        over R = ring M.  If omitted, koszulComplexDGA(ring M) is used.
      * M, a module (Macaulay2Doc), A module over A.ring.
  * Optional inputs (Macaulay2Doc),:
      * StartDegree,
        => an integer (Macaulay2Doc), default value 1, First
        hom-degree at which to start killing homology.  Defaults to 1.
      * EndDegree,
        => an integer (Macaulay2Doc), default value 3, Last
        hom-degree at which to kill homology.  Defaults to 3.  Homology of F in
        the range [StartDegree, EndDegree] will vanish.
  * Outputs:
      * F, an instance of the type DGModule, A free DG module
        over A with H_0(F) = M and H_n(F) = 0 for StartDegree <= n <=
        EndDegree.

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

Starts from a free DG module with one hom-degree-0 generator per generator of
M, adjoins hom-degree-1 generators whose differentials are the columns of
presentation M lifted to A.natural (killing the presentation relations), and
then iterates killCycles(DGModule), from
StartDegree through EndDegree.

This is the module-theoretic analog of acyclicClosure, on
a DG algebra.  The output is a semifree DG module but is not guaranteed to be
minimal over A: relation columns are adjoined even when they are already
boundaries under the DG algebra differential.  For a minimal resolution, use
minimalSemifreeResolution.

+--------------------------------------------------------------------+
|i1 : R = QQ[x]                                                      |
|                                                                    |
|o1 = R                                                              |
|                                                                    |
|o1 : PolynomialRing                                                 |
+--------------------------------------------------------------------+
|i2 : M = R^1 / ideal(x)                                             |
|                                                                    |
|o2 = cokernel | x |                                                 |
|                                                                    |
|                            1                                       |
|o2 : R-module, quotient of R                                        |
+--------------------------------------------------------------------+
|i3 : Mdg = semifreeResolution(koszulComplexDGA R, M, EndDegree => 3)|
|                                                                    |
|o3 = {Base ring => R                                   }            |
|      DG algebra => R[T   ]                                         |
|                       1,1                                          |
|                                 3                                  |
|      Natural module => (R[T   ])                                   |
|                            1,1                                     |
|      Generator degrees => {{0, 0}, {1, 1}, {2, 1}}                 |
|      Differentials on gens => {0, | x |, | -T_(1,1) |}             |
|                                   | 0 |  |     1    |              |
|                                   | 0 |  |     0    |              |
|                                                                    |
|o3 : DGModule                                                       |
+--------------------------------------------------------------------+
|i4 : prune homology(0, Mdg)                                         |
|                                                                    |
|o4 = cokernel | x |                                                 |
|                                                                    |
|                            1                                       |
|o4 : R-module, quotient of R                                        |
+--------------------------------------------------------------------+
|i5 : all(1..3, n -> prune homology(n, Mdg) == 0)                    |
|                                                                    |
|o5 = true                                                           |
+--------------------------------------------------------------------+

Over a complete intersection, the resolution is infinite but the truncation up
to any requested EndDegree is acyclic in positive hom-degrees up to that bound.

+-----------------------------------------------------------------------------+
|i6 : R = QQ[x, y] / ideal(x^2, y^2)                                          |
|                                                                             |
|o6 = R                                                                       |
|                                                                             |
|o6 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i7 : k = R^1 / ideal(x, y)                                                   |
|                                                                             |
|o7 = cokernel | x y |                                                        |
|                                                                             |
|                            1                                                |
|o7 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+
|i8 : Mdg = semifreeResolution(koszulComplexDGA R, k, EndDegree => 3)         |
|                                                                             |
|o8 = {Base ring => R                                                         |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       10                                    |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {1, 1}, {1, 1}, {2, 1}, {2, 1}, {2, 2}, {|
|      Differentials on gens => {0, | x |, | y |, | -T_(1,1) |, | -T_(1,2) |, |
|                                   | 0 |  | 0 |  |     1    |  |     0    |  |
|                                   | 0 |  | 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    |  |
|                                                                             |
|o8 : DGModule                                                                |
|-----------------------------------------------------------------------------|
|                                                                     }       |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|2, 2}, {4, 4}, {4, 4}, {4, 4}}                                               |
|| xT_(1,1) |, | yT_(1,2) |, |     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    |  | xT_(1,1) |  | yT_(1,2) |  |     0    |         |
||     0    |  |     0    |  |     0    |  | xT_(1,1) |  | yT_(1,2) |         |
||     0    |  |     0    |  |     0    |  |     0    |  |     0    |         |
||     0    |  |     0    |  |     0    |  |     0    |  |     0    |         |
||     0    |  |     0    |  |     0    |  |     0    |  |     0    |         |
+-----------------------------------------------------------------------------+
|i9 : all(1..3, i -> prune homology(i, Mdg) == 0)                             |
|                                                                             |
|o9 = true                                                                    |
+-----------------------------------------------------------------------------+

The Module-only form infers the DG algebra from ring M:

+---------------------------------------------------------+
|i10 : R = QQ[x]                                          |
|                                                         |
|o10 = R                                                  |
|                                                         |
|o10 : PolynomialRing                                     |
+---------------------------------------------------------+
|i11 : M = R^1 / ideal(x)                                 |
|                                                         |
|o11 = cokernel | x |                                     |
|                                                         |
|                             1                           |
|o11 : R-module, quotient of R                            |
+---------------------------------------------------------+
|i12 : Mdg = semifreeResolution(M, EndDegree => 2)        |
|                                                         |
|o12 = {Base ring => R                                   }|
|       DG algebra => R[T   ]                             |
|                        1,1                              |
|                                  3                      |
|       Natural module => (R[T   ])                       |
|                             1,1                         |
|       Generator degrees => {{0, 0}, {1, 1}, {2, 1}}     |
|       Differentials on gens => {0, | x |, | -T_(1,1) |} |
|                                    | 0 |  |     1    |  |
|                                    | 0 |  |     0    |  |
|                                                         |
|o12 : DGModule                                           |
+---------------------------------------------------------+
|i13 : Mdg.ring === R                                     |
|                                                         |
|o13 = true                                               |
+---------------------------------------------------------+
|i14 : Mdg.dgAlgebra.ring === R                           |
|                                                         |
|o14 = true                                               |
+---------------------------------------------------------+

Caveat
======

The output is not minimal in general; use minimalSemifreeResolution,
when a minimal presentation is required.  The base
ring of M must agree with A.ring in the two-argument form.

See also
========

  * Semifree resolutions of DG modules
    -- Building semifree DG module resolutions via koszulComplexDGM,
    adjoinGenerators, killCycles, and semifreeResolution
  * minimalSemifreeResolution -- Build a
    minimal semifree DG module resolution over a DG algebra
  * killCycles(DGModule) -- Adjoin free
    generators to kill the lowest nonvanishing homology of a DG module
  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension
  * koszulComplexDGM -- The Koszul complex of a module
    as a DG module

Ways to use semifreeResolution:
===============================

  * "semifreeResolution(DGAlgebra,Module)"
  * "semifreeResolution(Module)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5705:0.

semifreeResolution(...,StartDegree=>...) -- Option to specify the degree at which semifreeResolution starts killing cycles
**************************************************************************************************************************

  * Usage:
        semifreeResolution(..., StartDegree => n)

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

Controls the first hom-degree at which semifreeResolution,
attempts to kill homology. Hom-degrees strictly below
StartDegree are populated only by the initial free cover and the adjoinment of
presentation relations at hom-degree 1.  The default value is 1.

See also
========

  * semifreeResolution -- Build a semifree DG module
    resolving a module over the base ring
  * semifreeResolution(...,EndDegree=>...)
    -- Option to
    specify the last degree at which semifreeResolution kills cycles

Functions with optional argument named StartDegree:
===================================================

  * acyclicClosure(...,StartDegree=>...)
    -- Option to
    specify the degree to start computing the acyclic closure.
  * getGenerators(...,StartDegree=>...)
    -- First homological
    degree in which to search for new algebra generators
  * killCycles(...,StartDegree=>...)
    -- First homological
    degree from which killCycles begins searching for cycles
  * "minimalModel(...,StartDegree=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * minimalSemifreeResolution(...,StartDegree=>...),
    --
    Option to specify the degree at which minimalSemifreeResolution starts
    killing cycles
  * semifreeResolution(...,StartDegree=>...)
    -- Option to
    specify the degree at which semifreeResolution starts killing cycles

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

  * Default value: 1
  * Function: semifreeResolution, -- Build a semifree
    DG module resolving a module over the base ring
  * Option key: StartDegree, -- Option to specify the first
    homological degree processed by an iterative DG construction
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5725:0.

semifreeResolution(...,EndDegree=>...) -- Option to specify the last degree at which semifreeResolution kills cycles
********************************************************************************************************************

  * Usage:
        semifreeResolution(..., EndDegree => n)

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

Controls the last hom-degree at which semifreeResolution,
iterates killCycles(DGModule).
Homology of the output in the range [StartDegree,
EndDegree] vanishes; higher degrees are not resolved.  The default value is 3.

See also
========

  * semifreeResolution -- Build a semifree DG module
    resolving a module over the base ring
  * semifreeResolution(...,StartDegree=>...)
    -- Option to
    specify the degree at which semifreeResolution starts killing cycles

Functions with optional argument named EndDegree:
=================================================

  * acyclicClosure(...,EndDegree=>...)
    -- Option to specify
    the degree to stop computing the acyclic closure
  * isAcyclic(...,EndDegree=>...)
    -- Option to specify the
    degree to finish checking acyclicity
  * killCycles(...,EndDegree=>...)
    -- Last homological
    degree processed by killCycles
  * "liftToDGMap(...,EndDegree=>...)" -- see liftToDGMap, --
    Lift a ring homomorphism in degree zero to a DG algebra morphism
  * "liftToDGModuleMap(...,EndDegree=>...)" -- see liftToDGModuleMap,
    -- Lift an image of hom-degree-0 generators to a full
    DGModuleMap
  * "minimalModel(...,EndDegree=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * minimalSemifreeResolution(...,EndDegree=>...)
    -- Option
    to specify the last degree at which minimalSemifreeResolution kills cycles
  * semifreeResolution(...,EndDegree=>...)
    -- Option to
    specify the last degree at which semifreeResolution kills cycles
  * "toComplexMap(...,EndDegree=>...)" -- see toComplexMap,
    -- Construct the ComplexMap associated to a DGAlgebraMap

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

  * Default value: 3
  * Function: semifreeResolution, -- Build a semifree
    DG module resolving a module over the base ring
  * Option key: EndDegree, -- Option to specify the last
    homological degree processed by an iterative DG construction
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5744:0.

minimalSemifreeResolution -- Build a minimal semifree DG module resolution over a DG algebra
********************************************************************************************

  * Usage:
        F = minimalSemifreeResolution M
        F = minimalSemifreeResolution(A, M)
        F = minimalSemifreeResolution(A, M, EndDegree => n)
  * Inputs:
      * A, an instance of the type DGAlgebra, A DG algebra
        over a (graded-)local ring R = ring M.  If omitted,
        koszulComplexDGA(ring M) is used.
      * M, a module (Macaulay2Doc), A module over A.ring.
  * Optional inputs (Macaulay2Doc),:
      * StartDegree,
        => an integer (Macaulay2Doc), default value
        1, First hom-degree at which to start killing homology.  Defaults to 1.
      * EndDegree,
        => an integer (Macaulay2Doc), default value 3,
        Last hom-degree at which to kill homology.  Defaults to 3.
      * Minimize (missing documentation) => ..., default value true,
  * Outputs:
      * F, an instance of the type DGModule, A semifree DG
        module resolving M over A, minimal in the sense that every generator's
        differential lands in the augmentation ideal of A.natural.

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

Produces a semifree resolution whose generator count in each hom-degree is
minimal among all semifree resolutions of M over A.  Two ingredients make the
output minimal:

First, M is replaced by prune M, giving a minimal presentation over the
(graded-)local base ring.  The number of hom-degree-0 generators is therefore
the minimal number of generators of M over R.

Second, each column of presentation(prune M) is tested with
getBoundaryPreimage, against the DG-algebra-induced
differential.  If a relation is already a boundary, it is not adjoined; if only
a residue is a non-boundary, the adjoined generator's differential is that
residue rather than the original relation.  This is what makes the output
minimal over A, not merely over R.

The iterative killCycles(DGModule), passes then
use the canonical pruning map of homology(n, F) to pick a minimal generating
set of representative cycles at each stage.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)                                          |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : k = R^1 / ideal(x, y)                                                   |
|                                                                             |
|o2 = cokernel | x y |                                                        |
|                                                                             |
|                            1                                                |
|o2 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+
|i3 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o3 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,2                                     |
|      Differential => {x, y}                                                 |
|                                                                             |
|o3 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i4 : Mdg = minimalSemifreeResolution(A, k, EndDegree => 3)                   |
|                                                                             |
|o4 = {Base ring => R                                                         |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       6                                     |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}, {4, 4}, {4, 4}, {4, 4}}  |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |, |     0    |, |
|                                   |     0    |  |     0    |  | xT_(1,1) |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                                                             |
|o4 : DGModule                                                                |
|-----------------------------------------------------------------------------|
|                           }                                                 |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
||     0    |, |     0    |}                                                  |
|| yT_(1,2) |  |     0    |                                                   |
|| xT_(1,1) |  | yT_(1,2) |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
+-----------------------------------------------------------------------------+
|i5 : isMinimalSemifreeResolution Mdg                                         |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+
|i6 : all(1..3, i -> prune homology(i, Mdg) == 0)                             |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

Over the c.i. R = k[x, y]/(x^2, y^2) the minimal semifree resolution of k has
rank F_n = n+1, matching the Betti numbers of k over R.

+---------------------------------------------------------+
|i7 : apply(0..3, n -> numcols moduleDifferential(n, Mdg))|
|                                                         |
|o7 = (1, 2, 3, 4)                                        |
|                                                         |
|o7 : Sequence                                            |
+---------------------------------------------------------+

As with semifreeResolution, the Module-only form
infers koszulComplexDGA(ring M) as the DG algebra:

+--------------------------------------------------------+
|i8 : R = QQ[x]                                          |
|                                                        |
|o8 = R                                                  |
|                                                        |
|o8 : PolynomialRing                                     |
+--------------------------------------------------------+
|i9 : M = R^1 / ideal(x)                                 |
|                                                        |
|o9 = cokernel | x |                                     |
|                                                        |
|                            1                           |
|o9 : R-module, quotient of R                            |
+--------------------------------------------------------+
|i10 : Mdg = minimalSemifreeResolution(M, EndDegree => 2)|
|                                                        |
|o10 = {Base ring => R               }                   |
|       DG algebra => R[T   ]                            |
|                        1,1                             |
|                                  1                     |
|       Natural module => (R[T   ])                      |
|                             1,1                        |
|       Generator degrees => {{0, 0}}                    |
|       Differentials on gens => {0}                     |
|                                                        |
|o10 : DGModule                                          |
+--------------------------------------------------------+
|i11 : Mdg.ring === R                                    |
|                                                        |
|o11 = true                                              |
+--------------------------------------------------------+
|i12 : isMinimalSemifreeResolution Mdg                   |
|                                                        |
|o12 = true                                              |
+--------------------------------------------------------+

A more substantial example: take the Koszul DG algebra on a regular sequence
cutting out a complete intersection, and resolve a module over the resulting DG
algebra.  Here A = koszulComplexDGA(I_*) with I = (x^2, y^2) is a DG algebra
over Q = ZZ/101[x, y] whose degree-zero homology is the complete intersection
Q/I, and A itself is the minimal DG algebra resolution of Q/I over Q.  We
resolve the Q/I-module M = Q/(x^2, x*y, y^2) as a DG A-module:

+-----------------------------------------------------------------------------+
|i13 : Q = ZZ/101[x, y]                                                       |
|                                                                             |
|o13 = Q                                                                      |
|                                                                             |
|o13 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i14 : I = ideal(x^2, y^2)                                                    |
|                                                                             |
|              2   2                                                          |
|o14 = ideal (x , y )                                                         |
|                                                                             |
|o14 : Ideal of Q                                                             |
+-----------------------------------------------------------------------------+
|i15 : A = koszulComplexDGA(I_*)                                              |
|                                                                             |
|o15 = {Ring => Q                          }                                  |
|       Underlying algebra => Q[T   ..T   ]                                   |
|                                1,1   1,2                                    |
|                         2   2                                               |
|       Differential => {x , y }                                              |
|                                                                             |
|o15 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i16 : M = Q^1 / ideal(x^2, x*y, y^2)                                         |
|                                                                             |
|o16 = cokernel | x2 xy y2 |                                                  |
|                                                                             |
|                             1                                               |
|o16 : Q-module, quotient of Q                                                |
+-----------------------------------------------------------------------------+
|i17 : Mdg = minimalSemifreeResolution(A, M, EndDegree => 5)                  |
|                                                                             |
|o17 = {Base ring => Q                                                        |
|       DG algebra => Q[T   ..T   ]                                           |
|                        1,1   1,2                                            |
|                                        22                                   |
|       Natural module => (Q[T   ..T   ])                                     |
|                             1,1   1,2                                       |
|       Generator degrees => {{0, 0}, {1, 2}, {2, 3}, {2, 3}, {3, 4}, {3,     |
|       Differentials on gens => {0, | xy |, | xT_(1,2) |, | -yT_(1,1) |,     |
|                                    |  0 |  |    -y    |  |     x     |      |
|                                    |  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     |      |
|                                                                             |
|o17 : DGModule                                                               |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|4}, {3, 4}, {4, 5}, {4, 5}, {4, 5}, {4, 5}, {5, 6}, {5, 6}, {5, 6}, {5,      |
||    0    |, | -T_(1,1)T_(1,2) |, |     0    |, |     0    |, |    0         |
|| T_(1,2) |  |        0        |  | -T_(1,1) |  |     0    |  |    0         |
||    y    |  |        x        |  |     0    |  | -T_(1,2) |  |    0         |
||    0    |  |        y        |  |     x    |  |     0    |  | T_(1,2)      |
||    0    |  |        0        |  |     0    |  |     y    |  |    x         |
||    0    |  |        0        |  |     0    |  |     0    |  |    -y        |
||    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         |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|6}, {5, 6}, {6, 7}, {6, 7}, {6, 7}, {6, 7}, {6, 7}, {6, 7}}                  |
||, |     0    |, |     0    |, |     0    |, |     0    |, |     0    |, |   |
||  |     0    |  |     0    |  |     0    |  |     0    |  |     0    |  |   |
||  | -T_(1,1) |  |     0    |  |     0    |  |     0    |  |     0    |  |   |
||  |     0    |  | -T_(1,1) |  |     0    |  |     0    |  |     0    |  |   |
||  |     0    |  |     0    |  | -T_(1,2) |  |     0    |  | -T_(1,1) |  |   |
||  |     x    |  |     0    |  |     0    |  | -T_(1,2) |  |     0    |  |   |
||  |    -y    |  |     x    |  |     0    |  |     0    |  |  T_(1,2) |  |   |
||  |     0    |  |     0    |  |     y    |  |     x    |  |     0    |  |   |
||  |     0    |  |     0    |  |     0    |  |    -y    |  |     x    |  |   |
||  |     0    |  |     0    |  |     0    |  |     0    |  |     y    |  |   |
||  |     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    |  |        |
|-T_(1,1) |  |     0    |  |     0    |  |     0    |  |     0    |  |        |
|    0    |  | -T_(1,1) |  |     0    |  |     0    |  |     0    |  |        |
|    0    |  |     0    |  | -T_(1,2) |  |     0    |  | -T_(1,1) |  |        |
|    0    |  |     0    |  |     0    |  | -T_(1,2) |  |     0    |  |        |
|    x    |  |     0    |  |     0    |  |     0    |  | -T_(1,2) |  |        |
|    y    |  |     x    |  |     0    |  |     0    |  |     0    |  |        |
|    0    |  |     0    |  |     y    |  |     x    |  |     0    |  |        |
|    0    |  |     0    |  |     0    |  |    -y    |  |     x    |  |        |
|    0    |  |     0    |  |     0    |  |     0    |  |     y    |  |        |
|    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    |                                       |
|-T_(1,1) |  |     0    |  |     0    |                                       |
|    0    |  | -T_(1,1) |  |     0    |                                       |
| T_(1,2) |  |     0    |  | -T_(1,1) |                                       |
|    0    |  |     0    |  |     0    |                                       |
|    0    |  |     0    |  |     0    |                                       |
|    x    |  |     0    |  |     0    |                                       |
|   -y    |  |     x    |  |     0    |                                       |
|    0    |  |    -y    |  |     x    |                                       |
|    0    |  |     0    |  |     0    |                                       |
|    0    |  |     0    |  |     0    |                                       |
|    0    |  |     0    |  |     0    |                                       |
|    0    |  |     0    |  |     0    |                                       |
|    0    |  |     0    |  |     0    |                                       |
|    0    |  |     0    |  |     0    |                                       |
+-----------------------------------------------------------------------------+
|i18 : isMinimalSemifreeResolution Mdg                                        |
|                                                                             |
|o18 = true                                                                   |
+-----------------------------------------------------------------------------+
|i19 : all(1..5, i -> prune homology(i, Mdg) == 0)                            |
|                                                                             |
|o19 = true                                                                   |
+-----------------------------------------------------------------------------+
|i20 : apply(0..5, n -> numcols moduleDifferential(n, Mdg))                   |
|                                                                             |
|o20 = (1, 3, 5, 8, 12, 16)                                                   |
|                                                                             |
|o20 : Sequence                                                               |
+-----------------------------------------------------------------------------+

Matrix factorizations on hypersurfaces.  Over a hypersurface R = Q/(f) every
maximal Cohen-Macaulay module's free resolution is eventually 2-periodic with
differentials forming a matrix factorization (phi, psi) of f (Eisenbud).  The
minimal semifree resolution over A = koszulComplexDGA(ideal f) exhibits this
periodicity directly in its printed differentials.  Here is the classic example
f = x^5:

+-----------------------------------------------------------------------------+
|i21 : Q = ZZ/101[x]                                                          |
|                                                                             |
|o21 = Q                                                                      |
|                                                                             |
|o21 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i22 : A = koszulComplexDGA(ideal(x^5))                                       |
|                                                                             |
|o22 = {Ring => Q                    }                                        |
|       Underlying algebra => Q[T   ]                                         |
|                                1,1                                          |
|                         5                                                   |
|       Differential => {x }                                                  |
|                                                                             |
|o22 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i23 : Mdg = minimalSemifreeResolution(A, Q^1/ideal(x), EndDegree => 6)       |
|                                                                             |
|o23 = {Base ring => Q                                                        |
|       DG algebra => Q[T   ]                                                 |
|                        1,1                                                  |
|                                  8                                          |
|       Natural module => (Q[T   ])                                           |
|                             1,1                                             |
|       Generator degrees => {{0, 0}, {1, 1}, {2, 5}, {3, 6}, {4, 10}, {5,    |
|       Differentials on gens => {0, | x |, | -T_(1,1) |, |     0    |, |     |
|                                    | 0 |  |    x4    |  | -T_(1,1) |  |     |
|                                    | 0 |  |     0    |  |     x    |  | -   |
|                                    | 0 |  |     0    |  |     0    |  |     |
|                                    | 0 |  |     0    |  |     0    |  |     |
|                                    | 0 |  |     0    |  |     0    |  |     |
|                                    | 0 |  |     0    |  |     0    |  |     |
|                                    | 0 |  |     0    |  |     0    |  |     |
|                                                                             |
|o23 : DGModule                                                               |
|-----------------------------------------------------------------------------|
|                                                    }                        |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|11}, {6, 15}, {7, 16}}                                                       |
|   0    |, |     0    |, |     0    |, |     0    |}                         |
|   0    |  |     0    |  |     0    |  |     0    |                          |
|T_(1,1) |  |     0    |  |     0    |  |     0    |                          |
|  x4    |  | -T_(1,1) |  |     0    |  |     0    |                          |
|   0    |  |     x    |  | -T_(1,1) |  |     0    |                          |
|   0    |  |     0    |  |    x4    |  | -T_(1,1) |                          |
|   0    |  |     0    |  |     0    |  |     x    |                          |
|   0    |  |     0    |  |     0    |  |     0    |                          |
+-----------------------------------------------------------------------------+
|i24 : apply(1..6, n -> flatten entries moduleDifferential(n, Mdg))           |
|                                                                             |
|         5                5   4      4       5                5   4      4   |
|o24 = ({x , x}, {-x, -1, x , x }, {-x , -1, x , x}, {-x, -1, x , x }, {-x ,  |
|      -----------------------------------------------------------------------|
|           5                5   4                                            |
|      -1, x , x}, {-x, -1, x , x })                                          |
|                                                                             |
|o24 : Sequence                                                               |
+-----------------------------------------------------------------------------+

The 2x2 blocks alternate between an x-pattern and an x^4-pattern; their product
is x^5 times an identity matrix, which is exactly the matrix factorization x *
x^4 = x^5.  Similarly, for the quadric form f = x^2 + y^2 the module coker [[x,
y], [y, -x]] is already a matrix factorization of f, so its minimal semifree
resolution stabilizes in hom-degree one:

+-----------------------------------------------------------------------------+
|i25 : Q = ZZ/101[x, y]                                                       |
|                                                                             |
|o25 = Q                                                                      |
|                                                                             |
|o25 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i26 : A = koszulComplexDGA(ideal(x^2 + y^2))                                 |
|                                                                             |
|o26 = {Ring => Q                    }                                        |
|       Underlying algebra => Q[T   ]                                         |
|                                1,1                                          |
|                         2    2                                              |
|       Differential => {x  + y }                                             |
|                                                                             |
|o26 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i27 : M = coker matrix{{x, y}, {y, -x}}                                      |
|                                                                             |
|o27 = cokernel | x y  |                                                      |
|               | y -x |                                                      |
|                                                                             |
|                             2                                               |
|o27 : Q-module, quotient of Q                                                |
+-----------------------------------------------------------------------------+
|i28 : Mdg = minimalSemifreeResolution(A, M, EndDegree => 6)                  |
|                                                                             |
|o28 = {Base ring => Q                                                        |
|       DG algebra => Q[T   ]                                                 |
|                        1,1                                                  |
|                                  16                                         |
|       Natural module => (Q[T   ])                                           |
|                             1,1                                             |
|       Generator degrees => {{0, 0}, {0, 0}, {1, 1}, {1, 1}, {2,             |
|       Differentials on gens => {0, 0, | x |, | -y |, | -T_(1,1)             |
|                                       | y |  |  x |  |     0                |
|                                       | 0 |  |  0 |  |     x                |
|                                       | 0 |  |  0 |  |    -y                |
|                                       | 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                |
|                                                                             |
|o28 : DGModule                                                               |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|2}, {2, 2}, {3, 3}, {3, 3}, {4, 4}, {4, 4}, {5, 5}, {5,                      |
||, |     0    |, |     0    |, |     0    |, |     0                         |
||  | -T_(1,1) |  |     0    |  |     0    |  |     0                         |
||  |     y    |  | -T_(1,1) |  |     0    |  |     0                         |
||  |     x    |  |     0    |  | -T_(1,1) |  |     0                         |
||  |     0    |  |     x    |  |    -y    |  | -T_(1,1)                      |
||  |     0    |  |     y    |  |     x    |  |     0                         |
||  |     0    |  |     0    |  |     0    |  |     x                         |
||  |     0    |  |     0    |  |     0    |  |    -y                         |
||  |     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                         |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|5}, {6, 6}, {6, 6}, {7, 7}, {7, 7}}                                          |
||, |     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    |  |   |
||  | -T_(1,1) |  |     0    |  |     0    |  |     0    |  |     0    |  |   |
||  |     y    |  | -T_(1,1) |  |     0    |  |     0    |  |     0    |  |   |
||  |     x    |  |     0    |  | -T_(1,1) |  |     0    |  |     0    |  |   |
||  |     0    |  |     x    |  |    -y    |  | -T_(1,1) |  |     0    |  |   |
||  |     0    |  |     y    |  |     x    |  |     0    |  | -T_(1,1) |  |   |
||  |     0    |  |     0    |  |     0    |  |     x    |  |     y    |  |   |
||  |     0    |  |     0    |  |     0    |  |    -y    |  |     x    |  |   |
||  |     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    |                                                     |
|-T_(1,1) |  |     0    |                                                     |
|    0    |  | -T_(1,1) |                                                     |
|    x    |  |    -y    |                                                     |
|    y    |  |     x    |                                                     |
|    0    |  |     0    |                                                     |
|    0    |  |     0    |                                                     |
+-----------------------------------------------------------------------------+
|i29 : apply(0..6, n -> numcols moduleDifferential(n, Mdg))                   |
|                                                                             |
|o29 = (2, 4, 4, 4, 4, 4, 4)                                                  |
|                                                                             |
|o29 : Sequence                                                               |
+-----------------------------------------------------------------------------+

For the three-variable quadric f = x^2 + y^2 + z^2, resolving the residue field
stabilizes at rank 8, reflecting the 8-dimensional Clifford algebra of a
nondegenerate ternary quadratic form:

+-----------------------------------------------------------------------------+
|i30 : Q = ZZ/101[x, y, z]                                                    |
|                                                                             |
|o30 = Q                                                                      |
|                                                                             |
|o30 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i31 : A = koszulComplexDGA(ideal(x^2 + y^2 + z^2))                           |
|                                                                             |
|o31 = {Ring => Q                     }                                       |
|       Underlying algebra => Q[T   ]                                         |
|                                1,1                                          |
|                         2    2    2                                         |
|       Differential => {x  + y  + z }                                        |
|                                                                             |
|o31 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i32 : Mdg = minimalSemifreeResolution(A, Q^1/ideal(x, y,                     |
|                                                                             |
|o32 = {Base ring => Q                                                        |
|       DG algebra => Q[T   ]                                                 |
|                        1,1                                                  |
|                                  28                                         |
|       Natural module => (Q[T   ])                                           |
|                             1,1                                             |
|       Generator degrees => {{0, 0}, {1, 1}, {1, 1}, {1,                     |
|       Differentials on gens => {0, | z |, | y |, | x |,                     |
|                                    | 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 |                      |
|                                                                             |
|o32 : DGModule                                                               |
|-----------------------------------------------------------------------------|
|z), EndDegree => 6)                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|1}, {2, 2}, {2, 2}, {2, 2}, {2, 2}, {3, 3}, {3, 3}, {3, 3}, {3, 3}, {4, 4},  |
||  0 |, |  0 |, |  0 |, | -T_(1,1) |, |  0 |, |     0    |, |     0    |, |  |
||  y |  |  x |  |  0 |  |     z    |  |  0 |  | -T_(1,1) |  |     0    |  |  |
|| -z |  |  0 |  |  x |  |     y    |  |  0 |  |     0    |  | -T_(1,1) |  |  |
||  0 |  | -z |  | -y |  |     x    |  |  0 |  |     0    |  |     0    |  |  |
||  0 |  |  0 |  |  0 |  |     0    |  |  x |  |     y    |  |    -z    |  |  |
||  0 |  |  0 |  |  0 |  |     0    |  | -y |  |     x    |  |     0    |  |  |
||  0 |  |  0 |  |  0 |  |     0    |  |  z |  |     0    |  |     x    |  |  |
||  0 |  |  0 |  |  0 |  |     0    |  |  0 |  |     z    |  |     y    |  |  |
||  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    |  |  |
||  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    |  |  |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|{4, 4}, {4, 4}, {4, 4}, {5, 5}, {5, 5}, {5, 5}, {5, 5}, {6, 6}, {6,          |
|    0    |, |     0    |, |     0    |, |     0    |, |     0    |,          |
|    0    |  |     0    |  |     0    |  |     0    |  |     0    |           |
|    0    |  |     0    |  |     0    |  |     0    |  |     0    |           |
|-T_(1,1) |  |     0    |  |     0    |  |     0    |  |     0    |           |
|    0    |  | -T_(1,1) |  |     0    |  |     0    |  |     0    |           |
|   -z    |  |     0    |  | -T_(1,1) |  |     0    |  |     0    |           |
|   -y    |  |     0    |  |     0    |  | -T_(1,1) |  |     0    |           |
|    x    |  |     0    |  |     0    |  |     0    |  | -T_(1,1) |           |
|    0    |  |     x    |  |    -y    |  |     z    |  |     0    |           |
|    0    |  |     y    |  |     x    |  |     0    |  |     z    |           |
|    0    |  |    -z    |  |     0    |  |     x    |  |     y    |           |
|    0    |  |     0    |  |    -z    |  |    -y    |  |     x    |           |
|    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    |           |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|6}, {6, 6}, {6, 6}, {7, 7}, {7, 7}, {7, 7}, {7, 7}}                          |
||     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    |  |      |
|| -T_(1,1) |  |     0    |  |     0    |  |     0    |  |     0    |  |      |
||     0    |  | -T_(1,1) |  |     0    |  |     0    |  |     0    |  |      |
||     0    |  |     0    |  | -T_(1,1) |  |     0    |  |     0    |  |      |
||     0    |  |     0    |  |     0    |  | -T_(1,1) |  |     0    |  |      |
||     x    |  |     y    |  |    -z    |  |     0    |  | -T_(1,1) |  |      |
||    -y    |  |     x    |  |     0    |  |    -z    |  |     0    |  |      |
||     z    |  |     0    |  |     x    |  |    -y    |  |     0    |  |      |
||     0    |  |     z    |  |     y    |  |     x    |  |     0    |  |      |
||     0    |  |     0    |  |     0    |  |     0    |  |     x    |  |      |
||     0    |  |     0    |  |     0    |  |     0    |  |     y    |  |      |
||     0    |  |     0    |  |     0    |  |     0    |  |    -z    |  |      |
||     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    |  |     0    |  |     0    |  |        |
|    0    |  |     0    |  |     0    |  |     0    |  |     0    |  |        |
|    0    |  |     0    |  |     0    |  |     0    |  |     0    |  |        |
|-T_(1,1) |  |     0    |  |     0    |  |     0    |  |     0    |  |        |
|    0    |  | -T_(1,1) |  |     0    |  |     0    |  |     0    |  |        |
|    0    |  |     0    |  | -T_(1,1) |  |     0    |  |     0    |  |        |
|   -y    |  |     z    |  |     0    |  | -T_(1,1) |  |     0    |  |        |
|    x    |  |     0    |  |     z    |  |     0    |  | -T_(1,1) |  |        |
|    0    |  |     x    |  |     y    |  |     0    |  |     0    |  |        |
|   -z    |  |    -y    |  |     x    |  |     0    |  |     0    |  |        |
|    0    |  |     0    |  |     0    |  |     x    |  |     y    |  |        |
|    0    |  |     0    |  |     0    |  |    -y    |  |     x    |  |        |
|    0    |  |     0    |  |     0    |  |     z    |  |     0    |  |        |
|    0    |  |     0    |  |     0    |  |     0    |  |     z    |  |        |
|    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    |                                                     |
|-T_(1,1) |  |     0    |                                                     |
|    0    |  | -T_(1,1) |                                                     |
|   -z    |  |     0    |                                                     |
|    0    |  |    -z    |                                                     |
|    x    |  |    -y    |                                                     |
|    y    |  |     x    |                                                     |
|    0    |  |     0    |                                                     |
|    0    |  |     0    |                                                     |
|    0    |  |     0    |                                                     |
|    0    |  |     0    |                                                     |
+-----------------------------------------------------------------------------+
|i33 : apply(0..6, n -> numcols moduleDifferential(n, Mdg))                   |
|                                                                             |
|o33 = (1, 4, 7, 8, 8, 8, 8)                                                  |
|                                                                             |
|o33 : Sequence                                                               |
+-----------------------------------------------------------------------------+

Caveat
======

Minimality relies on A.ring being (graded-)local so that prune returns a
minimal presentation.  For A = koszulComplexDGA R with R a standard graded
quotient of a polynomial ring over a field, this is satisfied.

See also
========

  * Semifree resolutions of DG modules
    -- Building semifree DG module resolutions via koszulComplexDGM,
    adjoinGenerators, killCycles, and semifreeResolution
  * semifreeResolution -- Build a semifree DG module
    resolving a module over the base ring
  * isMinimalSemifreeResolution -- Test
    whether a semifree DG module is minimal over its DG algebra
  * getBoundaryPreimage -- Attempt to find a
    preimage of a boundary under the differential of a DGAlgebra.
  * killCycles(DGModule) -- Adjoin free
    generators to kill the lowest nonvanishing homology of a DG module

Ways to use minimalSemifreeResolution:
======================================

  * "minimalSemifreeResolution(DGAlgebra,Module)"
  * "minimalSemifreeResolution(Module)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5891:0.

minimalSemifreeResolution(...,StartDegree=>...) -- Option to specify the degree at which minimalSemifreeResolution starts killing cycles
****************************************************************************************************************************************

  * Usage:
        minimalSemifreeResolution(..., StartDegree => n)

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

Controls the first hom-degree at which minimalSemifreeResolution,
attempts to kill homology. The default is 1.

See also
========

  * minimalSemifreeResolution -- Build a
    minimal semifree DG module resolution over a DG algebra
  * minimalSemifreeResolution(...,EndDegree=>...)
    -- Option
    to specify the last degree at which minimalSemifreeResolution kills cycles

Functions with optional argument named StartDegree:
===================================================

  * acyclicClosure(...,StartDegree=>...)
    -- Option to
    specify the degree to start computing the acyclic closure.
  * getGenerators(...,StartDegree=>...)
    -- First homological
    degree in which to search for new algebra generators
  * killCycles(...,StartDegree=>...)
    -- First homological
    degree from which killCycles begins searching for cycles
  * "minimalModel(...,StartDegree=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * minimalSemifreeResolution(...,StartDegree=>...),
    --
    Option to specify the degree at which minimalSemifreeResolution starts
    killing cycles
  * semifreeResolution(...,StartDegree=>...)
    -- Option to
    specify the degree at which semifreeResolution starts killing cycles

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

  * Default value: 1
  * Function: minimalSemifreeResolution, --
    Build a minimal semifree DG module resolution over a DG algebra
  * Option key: StartDegree, -- Option to specify the first
    homological degree processed by an iterative DG construction
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5908:0.

minimalSemifreeResolution(...,EndDegree=>...) -- Option to specify the last degree at which minimalSemifreeResolution kills cycles
**********************************************************************************************************************************

  * Usage:
        minimalSemifreeResolution(..., EndDegree => n)

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

Controls the last hom-degree at which minimalSemifreeResolution,
iterates killCycles(DGModule).
Homology of the output in the range [StartDegree,
EndDegree] vanishes.  The default is 3.

See also
========

  * minimalSemifreeResolution -- Build a
    minimal semifree DG module resolution over a DG algebra
  * minimalSemifreeResolution(...,StartDegree=>...),
    --
    Option to specify the degree at which minimalSemifreeResolution starts
    killing cycles

Functions with optional argument named EndDegree:
=================================================

  * acyclicClosure(...,EndDegree=>...)
    -- Option to specify
    the degree to stop computing the acyclic closure
  * isAcyclic(...,EndDegree=>...)
    -- Option to specify the
    degree to finish checking acyclicity
  * killCycles(...,EndDegree=>...)
    -- Last homological
    degree processed by killCycles
  * "liftToDGMap(...,EndDegree=>...)" -- see liftToDGMap, --
    Lift a ring homomorphism in degree zero to a DG algebra morphism
  * "liftToDGModuleMap(...,EndDegree=>...)" -- see liftToDGModuleMap,
    -- Lift an image of hom-degree-0 generators to a full
    DGModuleMap
  * "minimalModel(...,EndDegree=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * minimalSemifreeResolution(...,EndDegree=>...)
    -- Option
    to specify the last degree at which minimalSemifreeResolution kills cycles
  * semifreeResolution(...,EndDegree=>...)
    -- Option to
    specify the last degree at which semifreeResolution kills cycles
  * "toComplexMap(...,EndDegree=>...)" -- see toComplexMap,
    -- Construct the ComplexMap associated to a DGAlgebraMap

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

  * Default value: 3
  * Function: minimalSemifreeResolution, --
    Build a minimal semifree DG module resolution over a DG algebra
  * Option key: EndDegree, -- Option to specify the last
    homological degree processed by an iterative DG construction
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5927:0.

isMinimalSemifreeResolution -- Test whether a semifree DG module is minimal over its DG algebra
***********************************************************************************************

  * Usage:
        b = isMinimalSemifreeResolution M
  * Inputs:
      * M, an instance of the type DGModule, A free DG module
        (the intended use is on the output of semifreeResolution,
        or minimalSemifreeResolution).
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), true when each
        generator's differential lies in the augmentation ideal of A.natural,
        i.e. its reduction along A -> k (sending T_i -> 0 and then mod (vars
        R)) is zero.

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

Minimality over a DG algebra A means: after base change along the augmentation
A -> k, every differential of F becomes the zero map.  Equivalently, each
M.diff#i has all of its coefficients (in the free basis of M.natural) lying in
the augmentation ideal of A.natural generated by (vars R) and the
positive-hom-degree generators T_i.

This predicate checks only the structural minimality condition; it does not
verify acyclicity.  Use isAcyclic(DGModule),
with an EndDegree option for that.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)                                          |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : k = R^1 / ideal(x, y)                                                   |
|                                                                             |
|o2 = cokernel | x y |                                                        |
|                                                                             |
|                            1                                                |
|o2 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+
|i3 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o3 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,2                                     |
|      Differential => {x, y}                                                 |
|                                                                             |
|o3 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i4 : Mdg = minimalSemifreeResolution(A, k, EndDegree => 3)                   |
|                                                                             |
|o4 = {Base ring => R                                                         |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       6                                     |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}, {4, 4}, {4, 4}, {4, 4}}  |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |, |     0    |, |
|                                   |     0    |  |     0    |  | xT_(1,1) |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                                                             |
|o4 : DGModule                                                                |
|-----------------------------------------------------------------------------|
|                           }                                                 |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
||     0    |, |     0    |}                                                  |
|| yT_(1,2) |  |     0    |                                                   |
|| xT_(1,1) |  | yT_(1,2) |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
+-----------------------------------------------------------------------------+
|i5 : isMinimalSemifreeResolution Mdg                                         |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+

A DG module built with a unit differential between free generators is not
minimal:

+--------------------------------------------------------------+
|i6 : R = QQ[x]                                                |
|                                                              |
|o6 = R                                                        |
|                                                              |
|o6 : PolynomialRing                                           |
+--------------------------------------------------------------+
|i7 : A = koszulComplexDGA R                                   |
|                                                              |
|o7 = {Ring => R                    }                          |
|      Underlying algebra => R[T   ]                           |
|                               1,1                            |
|      Differential => {x}                                     |
|                                                              |
|o7 : DGAlgebra                                                |
+--------------------------------------------------------------+
|i8 : Mbad = freeDGModule(A, {0, 1})                           |
|                                                              |
|o8 = {Base ring => R                       }                  |
|      DG algebra => R[T   ]                                   |
|                       1,1                                    |
|                                 2                            |
|      Natural module => (R[T   ])                             |
|                            1,1                               |
|      Generator degrees => {{0, 0}, {1, 0}}                   |
|      Differentials on gens => {0, 0}                         |
|                                                              |
|o8 : DGModule                                                 |
+--------------------------------------------------------------+
|i9 : natGens = apply(rank Mbad.natural, i -> (Mbad.natural)_i)|
|                                                              |
|o9 = {| 1 |, | 0 |}                                           |
|      | 0 |  | 1 |                                            |
|                                                              |
|o9 : List                                                     |
+--------------------------------------------------------------+
|i10 : setDiff(Mbad, {0, natGens#0})                           |
|                                                              |
|o10 = {Base ring => R                       }                 |
|       DG algebra => R[T   ]                                  |
|                        1,1                                   |
|                                  2                           |
|       Natural module => (R[T   ])                            |
|                             1,1                              |
|       Generator degrees => {{0, 0}, {1, 0}}                  |
|       Differentials on gens => {0, | 1 |}                    |
|                                    | 0 |                     |
|                                                              |
|o10 : DGModule                                                |
+--------------------------------------------------------------+
|i11 : isMinimalSemifreeResolution Mbad                        |
|                                                              |
|o11 = false                                                   |
+--------------------------------------------------------------+

Caveat
======

Returns false on DG modules whose underlying A.natural-module is not free (in
that case the generator differentials are not the right data to test).

See also
========

  * Semifree resolutions of DG modules
    -- Building semifree DG module resolutions via koszulComplexDGM,
    adjoinGenerators, killCycles, and semifreeResolution
  * minimalSemifreeResolution -- Build a
    minimal semifree DG module resolution over a DG algebra
  * semifreeResolution -- Build a semifree DG module
    resolving a module over the base ring
  * isAcyclic(DGModule) -- Determine whether a
    DG module has vanishing positive-degree homology

Ways to use isMinimalSemifreeResolution:
========================================

  * "isMinimalSemifreeResolution(DGModule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:5987:0.

Computing module differentials and visualizing DG modules -- Differential matrices, element-wise differentials, and visualization helpers for DG modules
********************************************************************************************************************************************************

Once a DGModule, M over a DGAlgebra, A is
built, the package supports two levels of access to the differential.

The matrix-level view is moduleDifferential,: the
call moduleDifferential(n, M) returns the hom-degree-n piece of d_M as a
homogeneous matrix over A.ring whose source and target are the free
A.ring-modules on the respective monomial bases of M_n and M_{n-1}.  The
block-structured variant moduleBlockDiff, partitions
this matrix into one summand per (i, v) label, where i indexes a generator of
M.natural and v is a chunk-degree vector on the variables of A.natural.  The
pretty-printer displayModuleBlockDiff, renders
this labeled block matrix with one label per row and column.

The element-level view is diff(M, v): apply the differential directly to a
homogeneous element v of M.natural via the Leibniz rule, returning a Vector in
M.natural of hom-degree one less.  This is the entry point used internally by
chain-map checks and by homologyClass(DGModule,Vector).

Two lightweight inspection helpers summarize the generator layout:
generatorTable, prints a one-row-per-generator table with
hom-degree, external degree, and differential; and dgModuleSummary,
tabulates, for each hom-degree in a requested range, the
number of freshly adjoined generators at that degree and the rank of F_n as an
A.ring-module.

+---------------------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)                            |
|                                                               |
|o1 = R                                                         |
|                                                               |
|o1 : QuotientRing                                              |
+---------------------------------------------------------------+
|i2 : k = R^1 / ideal(x, y)                                     |
|                                                               |
|o2 = cokernel | x y |                                          |
|                                                               |
|                            1                                  |
|o2 : R-module, quotient of R                                   |
+---------------------------------------------------------------+
|i3 : A = koszulComplexDGA R                                    |
|                                                               |
|o3 = {Ring => R                          }                     |
|      Underlying algebra => R[T   ..T   ]                      |
|                               1,1   1,2                       |
|      Differential => {x, y}                                   |
|                                                               |
|o3 : DGAlgebra                                                 |
+---------------------------------------------------------------+
|i4 : Mdg = minimalSemifreeResolution(A, k, EndDegree => 2)     |
|                                                               |
|o4 = {Base ring => R                                          }|
|      DG algebra => R[T   ..T   ]                              |
|                       1,1   1,2                               |
|                                       3                       |
|      Natural module => (R[T   ..T   ])                        |
|                            1,1   1,2                          |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}}            |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |} |
|                                   |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |
|                                                               |
|o4 : DGModule                                                  |
+---------------------------------------------------------------+
|i5 : d2 = moduleDifferential(2, Mdg)                           |
|                                                               |
|o5 = {1} | -y x 0 |                                            |
|     {1} | x  0 y |                                            |
|                                                               |
|             2      3                                          |
|o5 : Matrix R  <-- R                                           |
+---------------------------------------------------------------+
|i6 : d1 = moduleDifferential(1, Mdg)                           |
|                                                               |
|o6 = | x y |                                                   |
|                                                               |
|             1      2                                          |
|o6 : Matrix R  <-- R                                           |
+---------------------------------------------------------------+
|i7 : d1 * d2 == 0                                              |
|                                                               |
|o7 = true                                                      |
+---------------------------------------------------------------+

Over a complete intersection, the semifree resolution of the residue field has
well-defined differentials matching d^2 = 0 in every degree.

See also
========

  * Semifree resolutions of DG modules
    -- Building semifree DG module resolutions via koszulComplexDGM,
    adjoinGenerators, killCycles, and semifreeResolution
  * HH_ZZ DGModule -- The degree-n homology of a DG
    module as a module over the base ring

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6050:0.

moduleDifferential -- The hom-degree-n differential of a DG module as a matrix over the base ring
*************************************************************************************************

  * Usage:
        dn = moduleDifferential(n, M)
  * Inputs:
      * n, an integer (Macaulay2Doc), A hom-degree.
      * M, an instance of the type DGModule, A DG module over
        a DG algebra A; must be free (as in freeDGModule,
        output) or in koszulComplexDGM, form.
  * Outputs:
      * dn, a matrix (Macaulay2Doc), The component d_n : F_n ->
        F_{n-1} of the differential of M, as a homogeneous matrix over A.ring.
        Columns are indexed by the pairs (i, m) of moduleBasisPairs(M, n); rows
        by the pairs of moduleBasisPairs(M, n-1).

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

Two code paths are used internally:

When M comes from koszulComplexDGM, (so M.module is
set) and every generator differential is zero, d_n is the tensor product
polyDifferential(n, A) \otimes id_{M.module}.  This is the fast path.

For general free DG modules, d_n is computed monomial-by-monomial via the
Leibniz rule, extracting A.ring-linear coefficients in the target basis.
Results are cached per hom-degree in M.cache.diffs.

+---------------------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)                            |
|                                                               |
|o1 = R                                                         |
|                                                               |
|o1 : QuotientRing                                              |
+---------------------------------------------------------------+
|i2 : k = R^1 / ideal(x, y)                                     |
|                                                               |
|o2 = cokernel | x y |                                          |
|                                                               |
|                            1                                  |
|o2 : R-module, quotient of R                                   |
+---------------------------------------------------------------+
|i3 : A = koszulComplexDGA R                                    |
|                                                               |
|o3 = {Ring => R                          }                     |
|      Underlying algebra => R[T   ..T   ]                      |
|                               1,1   1,2                       |
|      Differential => {x, y}                                   |
|                                                               |
|o3 : DGAlgebra                                                 |
+---------------------------------------------------------------+
|i4 : Mdg = minimalSemifreeResolution(A, k, EndDegree => 2)     |
|                                                               |
|o4 = {Base ring => R                                          }|
|      DG algebra => R[T   ..T   ]                              |
|                       1,1   1,2                               |
|                                       3                       |
|      Natural module => (R[T   ..T   ])                        |
|                            1,1   1,2                          |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}}            |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |} |
|                                   |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |
|                                                               |
|o4 : DGModule                                                  |
+---------------------------------------------------------------+
|i5 : d1 = moduleDifferential(1, Mdg)                           |
|                                                               |
|o5 = | x y |                                                   |
|                                                               |
|             1      2                                          |
|o5 : Matrix R  <-- R                                           |
+---------------------------------------------------------------+
|i6 : d2 = moduleDifferential(2, Mdg)                           |
|                                                               |
|o6 = {1} | -y x 0 |                                            |
|     {1} | x  0 y |                                            |
|                                                               |
|             2      3                                          |
|o6 : Matrix R  <-- R                                           |
+---------------------------------------------------------------+
|i7 : d1 * d2 == 0                                              |
|                                                               |
|o7 = true                                                      |
+---------------------------------------------------------------+

Every column of d_{n-1} d_n is zero, which is the d^2 = 0 condition.

Caveat
======

Raises an error on non-free DG modules (for example, the natural module of a
DGQuotientModule).  In that setting, compute the
differential at the element level via diff(Q, v) or work with dgComplex.

See also
========

  * Computing module differentials and visualizing DG modules
    -- Differential matrices,
    element-wise differentials, and visualization helpers for DG modules
  * diff(DGModule,Vector) -- Apply the DG
    module differential to an element
  * moduleBlockDiff -- The hom-degree-n differential of
    a DG module as a labeled block matrix
  * polyDifferential -- Matrix and element-level
    differentials of a DG algebra
  * HH_ZZ DGModule -- The degree-n homology of a DG
    module as a module over the base ring

Ways to use moduleDifferential:
===============================

  * "moduleDifferential(ZZ,DGModule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6111:0.

diff(DGModule,Vector) -- Apply the DG module differential to an element
***********************************************************************

  * Function: diff (Macaulay2Doc),
  * Usage:
        dv = diff(M, v)
  * Inputs:
      * M, an instance of the type DGModule, A DG module.
      * v, a vector (Macaulay2Doc), A homogeneous element of
        M.natural.
  * Outputs:
      * dv, a vector (Macaulay2Doc), The image d_M(v) in
        M.natural, computed via the Leibniz rule.

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

Applies the Leibniz rule coordinate by coordinate.  If v = sum_i f_i \cdot e_i
where e_i are the free generators of M.natural and f_i \in A.natural, then
d_M(v) = sum_i (d_A(f_i) \cdot e_i + (-1)^{|f_i|} f_i \cdot d_M(e_i)) where
|f_i| is the hom-degree of f_i.

This element-level interface is the entry point for checking the cycle
condition on a candidate homology class and for defining DGModuleMap objects
without committing to the matrix-level bookkeeping of moduleDifferential.

+--------------------------------------------------------+
|i1 : R = QQ[x]                                          |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                    }                    |
|      Underlying algebra => R[T   ]                     |
|                               1,1                      |
|      Differential => {x}                               |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                        |
|                                                        |
|o3 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, 0}                   |
|                                                        |
|o3 : DGModule                                           |
+--------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                        |
|o4 = {| 1 |, | 0 |}                                     |
|      | 0 |  | 1 |                                      |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : setDiff(M, {0, x * natGens#0})                     |
|                                                        |
|o5 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, | x |}               |
|                                   | 0 |                |
|                                                        |
|o5 : DGModule                                           |
+--------------------------------------------------------+
|i6 : diff(M, natGens#1)                                 |
|                                                        |
|o6 = | x |                                              |
|     | 0 |                                              |
|                                                        |
|              2                                         |
|o6 : (R[T   ])                                          |
|         1,1                                            |
+--------------------------------------------------------+
|i7 : diff(M, natGens#0)                                 |
|                                                        |
|o7 = 0                                                  |
|                                                        |
|              2                                         |
|o7 : (R[T   ])                                          |
|         1,1                                            |
+--------------------------------------------------------+

Here d(e_1) = x \cdot e_0 and d(e_0) = 0.

See also
========

  * Computing module differentials and visualizing DG modules
    -- Differential matrices,
    element-wise differentials, and visualization helpers for DG modules
  * moduleDifferential -- The hom-degree-n
    differential of a DG module as a matrix over the base ring
  * diff(DGQuotientModule,Vector),
    -- Apply the induced differential on a DG quotient module to an element
  * diff(DGAlgebra,RingElement), --
    Apply the differential of a DGAlgebra to a ring element

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

  * diff(DGModule,Vector) -- Apply the DG
    module differential to an element
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6158:0.

diff(DGQuotientModule,Vector) -- Apply the induced differential on a DG quotient module to an element
*****************************************************************************************************

  * Function: diff (Macaulay2Doc),
  * Usage:
        dv = diff(Q, v)
  * Inputs:
      * Q, an instance of the type DGQuotientModule, A
        DG quotient module Q = M / S.
      * v, a vector (Macaulay2Doc), A homogeneous element of
        Q.natural.
  * Outputs:
      * dv, a vector (Macaulay2Doc), The image d_Q(v) in
        Q.natural.

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

Because the inclusion of S into M is a DG submodule (its columns are d-closed
in M), the differential of M descends to Q.  This method applies the Leibniz
rule to a representative in Q.natural without going through a matrix-level
differential, which is convenient because Q.natural is a cokernel rather than a
free module.

+--------------------------------------------------------+
|i1 : R = ZZ/101[x]                                      |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                    }                    |
|      Underlying algebra => R[T   ]                     |
|                               1,1                      |
|      Differential => {x}                               |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                        |
|                                                        |
|o3 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, 0}                   |
|                                                        |
|o3 : DGModule                                           |
+--------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                        |
|o4 = {| 1 |, | 0 |}                                     |
|      | 0 |  | 1 |                                      |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : setDiff(M, {0, x * natGens#0})                     |
|                                                        |
|o5 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, | x |}               |
|                                   | 0 |                |
|                                                        |
|o5 : DGModule                                           |
+--------------------------------------------------------+
|i6 : S = dgSubmodule(M, (id_(M.natural))_{1})           |
|                                                        |
|o6 = DGSubmodule of ambient DGModule                    |
|     Degrees  => {{1, 0}, {0, 0}}                       |
|                          2                             |
|     natural  => (R[T   ])                              |
|                     1,1                                |
|     inclusion => {0, 0} | 0 x |                        |
|                  {1, 0} | 1 0 |                        |
|                                                        |
|o6 : DGSubmodule                                        |
+--------------------------------------------------------+
|i7 : Q = M / S                                          |
|                                                        |
|o7 = DGQuotientModule Q = M / S                         |
|     Q.natural = cokernel {0, 0} | 0 x |                |
|                          {1, 0} | 1 0 |                |
|     Degrees   = {{0, 0}, {1, 0}}                       |
|                                                        |
|o7 : DGQuotientModule                                   |
+--------------------------------------------------------+
|i8 : projection Q                                       |
|                                                        |
|                         2                              |
|o8 = {Source => (R[T   ])              }                |
|                    1,1                                 |
|      Target => cokernel {0, 0} | 0 x |                 |
|                         {1, 0} | 1 0 |                 |
|      Natural => {0, 0} | 1 0 |                         |
|                 {1, 0} | 0 0 |                         |
|                                                        |
|o8 : DGModuleMap                                        |
+--------------------------------------------------------+
|i9 : diff(Q, (Q.natural)_0)                             |
|                                                        |
|o9 = 0                                                  |
|                                                        |
|o9 : Vector                                             |
+--------------------------------------------------------+

See also
========

  * Computing module differentials and visualizing DG modules
    -- Differential matrices,
    element-wise differentials, and visualization helpers for DG modules
  * diff(DGModule,Vector) -- Apply the DG
    module differential to an element
  * DGQuotientModule -- The class of quotient DG
    modules M / S
  * dgQuotientModule -- Construct the quotient DG
    module M / S

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

  * diff(DGQuotientModule,Vector),
    -- Apply the induced differential on a DG quotient module to an element
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6200:0.

generatorTable -- Display the generator list of a DG module with hom-degrees and differentials
**********************************************************************************************

  * Usage:
        t = generatorTable M
  * Inputs:
      * M, an instance of the type DGModule,
  * Outputs:
      * t, a net (Macaulay2Doc), A centered table with one row per
        generator.  Columns are the generator index i, the hom-degree, the
        remaining external degree, and the differential M.diff#i.

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

A convenient overview of the generator structure of a semifree DG module.
Particularly useful for inspecting the output of
minimalSemifreeResolution, or
semifreeResolution, where each iteration of
killCycles(DGModule), appends further generators.

+--------------------------------------------------------+
|i1 : R = QQ[x]                                          |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                    }                    |
|      Underlying algebra => R[T   ]                     |
|                               1,1                      |
|      Differential => {x}                               |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                        |
|                                                        |
|o3 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, 0}                   |
|                                                        |
|o3 : DGModule                                           |
+--------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                        |
|o4 = {| 1 |, | 0 |}                                     |
|      | 0 |  | 1 |                                      |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : setDiff(M, {0, x * natGens#0})                     |
|                                                        |
|o5 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, | x |}               |
|                                   | 0 |                |
|                                                        |
|o5 : DGModule                                           |
+--------------------------------------------------------+
|i6 : instance(generatorTable M, Net)                    |
|                                                        |
|o6 = true                                               |
+--------------------------------------------------------+

When M has no generators, the result is a single-row placeholder.

See also
========

  * Computing module differentials and visualizing DG modules
    -- Differential matrices,
    element-wise differentials, and visualization helpers for DG modules
  * dgModuleSummary -- Tabulate hom-degree-wise
    generator counts and free-rank counts for a DG module
  * moduleBlockDiff -- The hom-degree-n differential of
    a DG module as a labeled block matrix

Ways to use generatorTable:
===========================

  * "generatorTable(DGModule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6239:0.

dgModuleSummary -- Tabulate hom-degree-wise generator counts and free-rank counts for a DG module
*************************************************************************************************

  * Usage:
        t = dgModuleSummary M
        t = dgModuleSummary(M, n)
  * Inputs:
      * M, an instance of the type DGModule, A free DG module
        (for example from freeDGModule, or
        minimalSemifreeResolution).
      * n, an integer (Macaulay2Doc), Upper bound on the hom-degree
        range to display.  When omitted, maxDegree M is used; if that is
        infinity the method raises an error asking for an explicit bound.
  * Outputs:
      * t, a net (Macaulay2Doc), A centered table with one row per
        hom-degree in 0..n. Columns are the hom-degree k, the number of
        generators of M placed at hom-degree k (i.e. adjoined in that degree),
        and the rank of F_k as an A.ring-module.

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

A one-call overview of how the generators of M distribute across hom-degrees
and how that translates into base-ring ranks.  Matches the data fed into
moduleDifferential.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)                                          |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : k = R^1 / ideal(x, y)                                                   |
|                                                                             |
|o2 = cokernel | x y |                                                        |
|                                                                             |
|                            1                                                |
|o2 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+
|i3 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o3 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,2                                     |
|      Differential => {x, y}                                                 |
|                                                                             |
|o3 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i4 : Mdg = minimalSemifreeResolution(A, k, EndDegree => 3)                   |
|                                                                             |
|o4 = {Base ring => R                                                         |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       6                                     |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}, {4, 4}, {4, 4}, {4, 4}}  |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |, |     0    |, |
|                                   |     0    |  |     0    |  | xT_(1,1) |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                                                             |
|o4 : DGModule                                                                |
|-----------------------------------------------------------------------------|
|                           }                                                 |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
||     0    |, |     0    |}                                                  |
|| yT_(1,2) |  |     0    |                                                   |
|| xT_(1,1) |  | yT_(1,2) |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
+-----------------------------------------------------------------------------+
|i5 : instance(dgModuleSummary(Mdg, 3), Net)                                  |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+

Caveat
======

The one-argument form is only applicable when the underlying hom-grading of M
is bounded (for example when M is a koszulComplexDGM,
output over a polynomial ring).  For arbitrary semifree DG modules, pass an
explicit upper bound.

See also
========

  * Computing module differentials and visualizing DG modules
    -- Differential matrices,
    element-wise differentials, and visualization helpers for DG modules
  * generatorTable -- Display the generator list of a DG
    module with hom-degrees and differentials
  * moduleBlockDiff -- The hom-degree-n differential of
    a DG module as a labeled block matrix
  * moduleDifferential -- The hom-degree-n
    differential of a DG module as a matrix over the base ring

Ways to use dgModuleSummary:
============================

  * "dgModuleSummary(DGModule)"
  * "dgModuleSummary(DGModule,ZZ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6289:0.

moduleBlockDiff -- The hom-degree-n differential of a DG module as a labeled block matrix
*****************************************************************************************

  * Usage:
        b = moduleBlockDiff(M, n)
  * Inputs:
      * M, an instance of the type DGModule, A DG module over
        a DG algebra A; must be free.
      * n, an integer (Macaulay2Doc), A hom-degree.
  * Outputs:
      * b, a matrix (Macaulay2Doc), The hom-degree-n differential
        of M, assembled as a map between direct sums indexed by pairs {i, v}
        (generator index plus variable-chunk-degree vector).

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

A block-structured refinement of moduleDifferential.
The source of the resulting map is a direct sum of small free A.ring-modules,
one per pair {i, v}, where i is the generator index of M.natural and v is a
tuple of exponents giving the chunk-degrees of A.natural-monomials contributing
to F_n.  Composing with matrix recovers exactly moduleDifferential(n, M).

Results are cached in M.cache#"moduleBlockDiffs" per n, so repeated calls are
cheap.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)                                          |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : k = R^1 / ideal(x, y)                                                   |
|                                                                             |
|o2 = cokernel | x y |                                                        |
|                                                                             |
|                            1                                                |
|o2 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+
|i3 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o3 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,2                                     |
|      Differential => {x, y}                                                 |
|                                                                             |
|o3 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i4 : Mdg = minimalSemifreeResolution(A, k, EndDegree => 3)                   |
|                                                                             |
|o4 = {Base ring => R                                                         |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       6                                     |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}, {4, 4}, {4, 4}, {4, 4}}  |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |, |     0    |, |
|                                   |     0    |  |     0    |  | xT_(1,1) |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                                                             |
|o4 : DGModule                                                                |
|-----------------------------------------------------------------------------|
|                           }                                                 |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
||     0    |, |     0    |}                                                  |
|| yT_(1,2) |  |     0    |                                                   |
|| xT_(1,1) |  | yT_(1,2) |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
+-----------------------------------------------------------------------------+
|i5 : b2 = moduleBlockDiff(Mdg, 2)                                            |
|                                                                             |
|o5 = {1} | -y x 0 |                                                          |
|     {1} | x  0 y |                                                          |
|                                                                             |
|             2      3                                                        |
|o5 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i6 : matrix b2 == moduleDifferential(2, Mdg)                                 |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+
|i7 : srcIdx = indices source b2                                              |
|                                                                             |
|o7 = {{0, {2}}, {1, {0}}, {2, {0}}}                                          |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : all(srcIdx, l -> #l == 2 and instance(l#0, ZZ) and instance(l#1, List)) |
|                                                                             |
|o8 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * Computing module differentials and visualizing DG modules
    -- Differential matrices,
    element-wise differentials, and visualization helpers for DG modules
  * displayModuleBlockDiff -- Pretty-print the
    labeled block matrix of a DG module differential
  * moduleDifferential -- The hom-degree-n
    differential of a DG module as a matrix over the base ring

Ways to use moduleBlockDiff:
============================

  * "moduleBlockDiff(DGModule,ZZ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6339:0.

displayModuleBlockDiff -- Pretty-print the labeled block matrix of a DG module differential
*******************************************************************************************

  * Usage:
        tab = displayModuleBlockDiff(M, n)
        entry = displayModuleBlockDiff(M, srcLbl, tgtLbl)
  * Inputs:
      * M, an instance of the type DGModule, A DG module; must
        be free.
      * n, an integer (Macaulay2Doc), A hom-degree.
      * srcLbl, a list (Macaulay2Doc), A pair {i, v} identifying a
        single source block (a generator index and a chunk-degree vector).
      * tgtLbl, a list (Macaulay2Doc), A pair {j, w} identifying a
        single target block.
  * Outputs:
      * tab, a net (Macaulay2Doc), A centered table whose first row
        lists source labels and whose first column lists target labels; inner
        entries are the corresponding blocks of moduleBlockDiff(M, n).
      * entry, a matrix (Macaulay2Doc), In the three-argument
        form, returns the single block b^[tgtLbl]_[srcLbl] extracted from the
        labeled block matrix.

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

The two-argument form lays out moduleBlockDiff, as a
labeled table, parallel to displayBlockDiff for DG algebras.  The
three-argument form bypasses the table and returns a single block directly,
which is handy for programmatic inspection.

+---------------------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)                            |
|                                                               |
|o1 = R                                                         |
|                                                               |
|o1 : QuotientRing                                              |
+---------------------------------------------------------------+
|i2 : k = R^1 / ideal(x, y)                                     |
|                                                               |
|o2 = cokernel | x y |                                          |
|                                                               |
|                            1                                  |
|o2 : R-module, quotient of R                                   |
+---------------------------------------------------------------+
|i3 : A = koszulComplexDGA R                                    |
|                                                               |
|o3 = {Ring => R                          }                     |
|      Underlying algebra => R[T   ..T   ]                      |
|                               1,1   1,2                       |
|      Differential => {x, y}                                   |
|                                                               |
|o3 : DGAlgebra                                                 |
+---------------------------------------------------------------+
|i4 : Mdg = minimalSemifreeResolution(A, k, EndDegree => 2)     |
|                                                               |
|o4 = {Base ring => R                                          }|
|      DG algebra => R[T   ..T   ]                              |
|                       1,1   1,2                               |
|                                       3                       |
|      Natural module => (R[T   ..T   ])                        |
|                            1,1   1,2                          |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}}            |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |} |
|                                   |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |
|                                                               |
|o4 : DGModule                                                  |
+---------------------------------------------------------------+
|i5 : instance(displayModuleBlockDiff(Mdg, 2), Net)             |
|                                                               |
|o5 = true                                                      |
+---------------------------------------------------------------+

See also
========

  * Computing module differentials and visualizing DG modules
    -- Differential matrices,
    element-wise differentials, and visualization helpers for DG modules
  * moduleBlockDiff -- The hom-degree-n differential of
    a DG module as a labeled block matrix
  * moduleDifferential -- The hom-degree-n
    differential of a DG module as a matrix over the base ring

Ways to use displayModuleBlockDiff:
===================================

  * "displayModuleBlockDiff(DGModule,List,List)"
  * "displayModuleBlockDiff(DGModule,ZZ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6387:0.

Building DG algebras from existing DG algebras -- Base change, generator restriction, truncation, and targeted cycle-killing for DG algebras
********************************************************************************************************************************************

Given an existing DGAlgebra, A, the package supports several
ways to derive new DG algebras from it.  All of these constructions preserve
the graded-commutative and Leibniz structure by design; most perform safety
checks before returning.

See baseChange, moves a DG algebra along a ring map on its base:
given A over R and a ring map phi: R -> S (or simply a target ring S, in which
case map(S, R) is used), baseChange returns a DG algebra over S whose generator
list and differentials are obtained by transporting scalars along phi.

See subDGAlgebra, produces a sub-DG algebra of A generated by a
chosen subset of the DG generators.  The subset must be d-closed: it is an
error if the differential of a kept generator uses a dropped one. See
restrictDifferential, is a synonym. See
truncateGenerators, is a convenience wrapper:
truncateGenerators(A, n) calls subDGAlgebra with the generators of hom-degree
strictly greater than n.

See killHomologyAtDegree, targets a specific hom-degree
n: it computes minimal representatives of H_n(A) and adjoins variables in
hom-degree n+1 whose differentials are those representatives, producing a new
DG algebra with H_n = 0.

All four constructions take optional arguments
InitializeDegreeZeroHomology, and InitializeComplex,
controlling how much of the downstream cache is eagerly populated by the
internal call to setDiff.

Two low-level predicates round out the family: isValidDGAlgebra,
performs a structural-invariant check (keys and types), and
isWellDefinedDifferential, performs the
semantic d^2 = 0 check on every generator.  Both are called internally by
isWellDefined(DGAlgebra).

+------------------------------------------+
|i1 : R = QQ[x, y]                         |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : S = R / ideal(x^2, y^2)              |
|                                          |
|o2 = S                                    |
|                                          |
|o2 : QuotientRing                         |
+------------------------------------------+
|i3 : A = koszulComplexDGA R               |
|                                          |
|o3 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o3 : DGAlgebra                            |
+------------------------------------------+
|i4 : B = baseChange(A, S)                 |
|                                          |
|o4 = {Ring => S                          }|
|      Underlying algebra => S[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o4 : DGAlgebra                            |
+------------------------------------------+
|i5 : underlyingRing B === S               |
|                                          |
|o5 = true                                 |
+------------------------------------------+
|i6 : isWellDefinedDifferential B          |
|                                          |
|o6 = true                                 |
+------------------------------------------+

Moving a Koszul DG algebra from a polynomial ring to a complete intersection
factor preserves d^2 = 0 because the differential expressions d(T_i) = x_i
remain valid in S.

See also
========

  * freeDGAlgebra -- Construct a free DG algebra with
    given generator degrees
  * koszulComplexDGA -- The Koszul complex on the
    variables of a ring, as a DG algebra
  * setDiff -- Install or replace the differential on a DG
    algebra
  * isWellDefined(DGAlgebra) -- Check that
    a DG algebra has correct structure and a differential that squares to zero
  * adjoinVariables -- Extend a DG algebra by a
    user-chosen list of cycles to be killed
  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6464:0.

baseChange -- Transport a DG algebra along a ring map on its base
*****************************************************************

  * Usage:
        B = baseChange(A, S)
        B = baseChange(A, phi)
  * Inputs:
      * A, an instance of the type DGAlgebra, A DG algebra
        over some ring R.
      * S, a ring (Macaulay2Doc), A target ring.  Shorthand for
        baseChange(A, map(S, R)).
      * phi, a ring map (Macaulay2Doc), A ring map with source R
        = underlyingRing A; its target becomes the base ring of B.
  * Optional inputs (Macaulay2Doc),:
      * InitializeDegreeZeroHomology => a Boolean value (Macaulay2Doc),
        default value true, Whether to compute H_0 of
        the result eagerly.  Default true.
      * InitializeComplex => a Boolean value (Macaulay2Doc),
        default value false, Whether to build the underlying complex of B
        eagerly.  Default false.
  * Outputs:
      * B, an instance of the type DGAlgebra, A DG algebra
        over target phi with the same generator hom-degrees as A, and whose
        differentials are the images of A.diff under the obvious extension of
        phi that sends each A-generator to the corresponding B-generator.

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

Useful for lifting a Koszul DG algebra over a polynomial ring to one over a
factor ring, or for specialization (via a ring map that kills some variables).

+------------------------------------------+
|i1 : R = QQ[x, y]                         |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : S = R / ideal(x^2, y^2)              |
|                                          |
|o3 = S                                    |
|                                          |
|o3 : QuotientRing                         |
+------------------------------------------+
|i4 : B = baseChange(A, S)                 |
|                                          |
|o4 = {Ring => S                          }|
|      Underlying algebra => S[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o4 : DGAlgebra                            |
+------------------------------------------+
|i5 : underlyingRing B === S               |
|                                          |
|o5 = true                                 |
+------------------------------------------+
|i6 : isWellDefinedDifferential B          |
|                                          |
|o6 = true                                 |
+------------------------------------------+

An explicit ring map gives more flexibility:

+-------------------------------------------+
|i7 : R = QQ[x, y]                          |
|                                           |
|o7 = R                                     |
|                                           |
|o7 : PolynomialRing                        |
+-------------------------------------------+
|i8 : A = koszulComplexDGA R                |
|                                           |
|o8 = {Ring => R                          } |
|      Underlying algebra => R[T   ..T   ]  |
|                               1,1   1,2   |
|      Differential => {x, y}               |
|                                           |
|o8 : DGAlgebra                             |
+-------------------------------------------+
|i9 : phi = map(R, R, {x, 0})               |
|                                           |
|o9 = map (R, R, {x, 0})                    |
|                                           |
|o9 : RingMap R <-- R                       |
+-------------------------------------------+
|i10 : Bphi = baseChange(A, phi)            |
|                                           |
|o10 = {Ring => R                          }|
|       Underlying algebra => R[T   ..T   ] |
|                                1,1   1,2  |
|       Differential => {x, 0}              |
|                                           |
|o10 : DGAlgebra                            |
+-------------------------------------------+
|i11 : underlyingRing Bphi === R            |
|                                           |
|o11 = true                                 |
+-------------------------------------------+

Caveat
======

Raises an error if source phi is not equal to underlyingRing A.

See also
========

  * Building DG algebras from existing DG algebras
    -- Base change, generator restriction,
    truncation, and targeted cycle-killing for DG algebras
  * DGAlgebra ** Ring -- Base change of a DG
    algebra to another ring
  * InitializeDegreeZeroHomology -- Install or replace the
    differential on a DG algebra
  * InitializeComplex -- Install or replace the differential on
    a DG algebra

Ways to use baseChange:
=======================

  * "baseChange(DGAlgebra,Ring)"
  * "baseChange(DGAlgebra,RingMap)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6527:0.

subDGAlgebra -- The sub-DG algebra generated by a chosen subset of DG generators
********************************************************************************

  * Usage:
        B = subDGAlgebra(A, keepIdx)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * keepIdx, a list (Macaulay2Doc), A list of integers giving
        the indices (into 0 .. numgens A.natural - 1) of the DG generators to
        keep.  Duplicates and out-of-range indices raise an error.
  * Optional inputs (Macaulay2Doc),:
      * InitializeDegreeZeroHomology => a Boolean value (Macaulay2Doc),
        default value true, Whether to compute H_0 of
        the result eagerly. Default true.
      * InitializeComplex => a Boolean value (Macaulay2Doc),
        default value false, Whether to build the underlying complex eagerly.
        Default false.
  * Outputs:
      * B, an instance of the type DGAlgebra, A DG algebra
        over A.ring whose DG generators are the keepIdx-indexed generators of A
        in sorted order, with their differentials restricted accordingly.

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

The subset keepIdx must be d-closed: if the differential of a kept generator
uses a dropped generator, subDGAlgebra raises an error rather than silently
returning a non-DG object.  This protects downstream code from accidentally
producing inconsistent structures.

+------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)       |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : QuotientRing                         |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : B = subDGAlgebra(A, {0})             |
|                                          |
|o3 = {Ring => R                    }      |
|      Underlying algebra => R[T   ]       |
|                               1,1        |
|      Differential => {x}                 |
|                                          |
|o3 : DGAlgebra                            |
+------------------------------------------+
|i4 : numgens B.natural                    |
|                                          |
|o4 = 1                                    |
+------------------------------------------+

Dropping a generator whose image is referenced in a kept generator's
differential is caught:

+-----------------------------------------------------------------------------+
|i5 : R = QQ[x] / ideal(x^2)                                                  |
|                                                                             |
|o5 = R                                                                       |
|                                                                             |
|o5 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i6 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o6 = {Ring => R                    }                                         |
|      Underlying algebra => R[T   ]                                          |
|                               1,1                                           |
|      Differential => {x}                                                    |
|                                                                             |
|o6 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i7 : A' = adjoinVariables(A, {x * (gens A.natural)#0})                       |
|                                                                             |
|o7 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   , T   ]                                    |
|                               1,1   2,1                                     |
|      Differential => {x, x*T   }                                            |
|                             1,1                                             |
|                                                                             |
|o7 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i8 : try subDGAlgebra(A', {1}) else "error: kept differential uses dropped   |
|                                                                             |
|o8 = error: kept differential uses dropped generator                         |
|-----------------------------------------------------------------------------|
|generator"                                                                   |
+-----------------------------------------------------------------------------+

Caveat
======

Duplicate or out-of-range entries in keepIdx raise an error.  keepIdx is
internally sorted, so the generator order of the output depends only on which
indices appear.

See also
========

  * Building DG algebras from existing DG algebras
    -- Base change, generator restriction,
    truncation, and targeted cycle-killing for DG algebras
  * restrictDifferential -- Synonym for
    subDGAlgebra, named to match the restricted-differential vocabulary
  * truncateGenerators -- Restrict a DG algebra to
    its generators of hom-degree strictly above a bound

Ways to use subDGAlgebra:
=========================

  * "subDGAlgebra(DGAlgebra,List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6585:0.

restrictDifferential -- Synonym for subDGAlgebra, named to match the restricted-differential vocabulary
*******************************************************************************************************

  * Usage:
        B = restrictDifferential(A, keepIdx)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * keepIdx, a list (Macaulay2Doc), List of integers giving DG
        generator indices to keep.
  * Optional inputs (Macaulay2Doc),:
      * InitializeDegreeZeroHomology => a Boolean value (Macaulay2Doc),
        default value true, Default true.
      * InitializeComplex => a Boolean value (Macaulay2Doc),
        default value false, Default false.
  * Outputs:
      * B, an instance of the type DGAlgebra, Identical to
        subDGAlgebra(A, keepIdx).

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

Calls directly into subDGAlgebra.  The two are
interchangeable; restrictDifferential is provided so that calling code
emphasizing the restricted-differential aspect reads more naturally.

+------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)       |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : QuotientRing                         |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : B = restrictDifferential(A, {0})     |
|                                          |
|o3 = {Ring => R                    }      |
|      Underlying algebra => R[T   ]       |
|                               1,1        |
|      Differential => {x}                 |
|                                          |
|o3 : DGAlgebra                            |
+------------------------------------------+
|i4 : numgens B.natural                    |
|                                          |
|o4 = 1                                    |
+------------------------------------------+

See also
========

  * Building DG algebras from existing DG algebras
    -- Base change, generator restriction,
    truncation, and targeted cycle-killing for DG algebras
  * subDGAlgebra -- The sub-DG algebra generated by a
    chosen subset of DG generators

Ways to use restrictDifferential:
=================================

  * "restrictDifferential(DGAlgebra,List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6622:0.

truncateGenerators -- Restrict a DG algebra to its generators of hom-degree strictly above a bound
**************************************************************************************************

  * Usage:
        B = truncateGenerators(A, n)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * n, an integer (Macaulay2Doc), A hom-degree bound; generators
        of hom-degree <= n are dropped.
  * Optional inputs (Macaulay2Doc),:
      * InitializeDegreeZeroHomology => a Boolean value (Macaulay2Doc),
        default value true, Default true.
      * InitializeComplex => a Boolean value (Macaulay2Doc),
        default value false, Default false.
  * Outputs:
      * B, an instance of the type DGAlgebra, The sub-DG
        algebra of A generated by the DG generators whose first-hom-degree
        component is strictly greater than n.

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

Computes keepIdx as select(0 .. #A.Degrees - 1, i -> first A.Degrees#i > n) and
delegates to subDGAlgebra.  As with subDGAlgebra,
the subset must be d-closed; if the differential of a generator
T_i of hom-degree > n uses a generator of hom-degree <= n that would be
dropped, an error is raised.

+------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)       |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : QuotientRing                         |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : B = truncateGenerators(A, 0)         |
|                                          |
|o3 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o3 : DGAlgebra                            |
+------------------------------------------+
|i4 : numgens B.natural                    |
|                                          |
|o4 = 2                                    |
+------------------------------------------+

The Koszul algebra has all generators in hom-degree 1 so truncating below
degree 0 is a no-op in this case.

See also
========

  * Building DG algebras from existing DG algebras
    -- Base change, generator restriction,
    truncation, and targeted cycle-killing for DG algebras
  * subDGAlgebra -- The sub-DG algebra generated by a
    chosen subset of DG generators

Ways to use truncateGenerators:
===============================

  * "truncateGenerators(DGAlgebra,ZZ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6669:0.

killHomologyAtDegree -- Adjoin variables killing the homology of a DG algebra at a prescribed degree
****************************************************************************************************

  * Usage:
        B = killHomologyAtDegree(A, n)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * n, an integer (Macaulay2Doc), The hom-degree at which to kill
        homology.
  * Outputs:
      * B, an instance of the type DGAlgebra, Either A itself
        (if H_n(A) = 0) or a new DG algebra obtained from A by adjoining
        variables in hom-degree n + 1 whose differentials are minimal
        representatives of H_n(A).

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

Unlike killCycles, which searches for the first nontrivial
degree upward from StartDegree, this method targets a specific degree.  It
computes the minimal generators of H_n(A) using the pruning map of prune
homology(n, A), lifts them to cycles in A_n, and adjoins via
adjoinVariables.

+------------------------------------------+
|i1 : R = QQ[x, y]                         |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : killHomologyAtDegree(A, 1) === A     |
|                                          |
|o3 = true                                 |
+------------------------------------------+

Over a regular ring, H_1 vanishes already, so the method short-circuits.  Over
a complete intersection, it adjoins new generators:

+---------------------------------------------+
|i4 : R = QQ[x, y] / ideal(x^2, y^2)          |
|                                             |
|o4 = R                                       |
|                                             |
|o4 : QuotientRing                            |
+---------------------------------------------+
|i5 : A = koszulComplexDGA R                  |
|                                             |
|o5 = {Ring => R                          }   |
|      Underlying algebra => R[T   ..T   ]    |
|                               1,1   1,2     |
|      Differential => {x, y}                 |
|                                             |
|o5 : DGAlgebra                               |
+---------------------------------------------+
|i6 : B = killHomologyAtDegree(A, 1)          |
|                                             |
|o6 = {Ring => R                             }|
|      Underlying algebra => R[T   ..T   ]    |
|                               1,1   2,2     |
|      Differential => {x, y, x*T   , y*T   } |
|                                1,1     1,2  |
|                                             |
|o6 : DGAlgebra                               |
+---------------------------------------------+
|i7 : numgens B.natural > numgens A.natural   |
|                                             |
|o7 = true                                    |
+---------------------------------------------+
|i8 : prune homology(1, B)                    |
|                                             |
|o8 = 0                                       |
|                                             |
|o8 : R-module                                |
+---------------------------------------------+

See also
========

  * Building DG algebras from existing DG algebras
    -- Base change, generator restriction,
    truncation, and targeted cycle-killing for DG algebras
  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree
  * adjoinVariables -- Extend a DG algebra by a
    user-chosen list of cycles to be killed
  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension

Ways to use killHomologyAtDegree:
=================================

  * "killHomologyAtDegree(DGAlgebra,ZZ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6716:0.

isValidDGAlgebra -- Structural invariant check for a DG algebra
***************************************************************

  * Usage:
        b = isValidDGAlgebra A
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), true when A has all
        required keys of the expected types (ring, natural algebra, degree
        list, differential list, cache table).

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

A lightweight structural check, intended to guard downstream code against
hand-assembled or corrupted DGAlgebra hash tables.  It does not check the d^2 =
0 condition; for that, use isWellDefinedDifferential,
or the user-facing isWellDefined(DGAlgebra).

+------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)       |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : QuotientRing                         |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : isValidDGAlgebra A                   |
|                                          |
|o3 = true                                 |
+------------------------------------------+

See also
========

  * Building DG algebras from existing DG algebras
    -- Base change, generator restriction,
    truncation, and targeted cycle-killing for DG algebras
  * isWellDefinedDifferential -- Semantic
    check that d^2 = 0 for a DG algebra or DG module
  * isWellDefined(DGAlgebra) -- Check that
    a DG algebra has correct structure and a differential that squares to zero

Ways to use isValidDGAlgebra:
=============================

  * "isValidDGAlgebra(DGAlgebra)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6749:0.

isWellDefinedDifferential -- Semantic check that d^2 = 0 for a DG algebra or DG module
**************************************************************************************

  * Usage:
        b = isWellDefinedDifferential A
        b = isWellDefinedDifferential M
  * Inputs:
      * A, an instance of the type DGAlgebra, A DG algebra.
      * M, an instance of the type DGModule, A DG module.
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), true when the
        composition d_{n-1} * d_n is zero for every relevant n.

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

The semantic half of the well-definedness check: it verifies that the
differential squares to zero on every generator.  The structural half (see
isValidDGAlgebra, and the corresponding isValidDGModule for
modules) is called first as a pre-condition.

This is the primitive called internally by isWellDefined(DGAlgebra),
and the user-facing
isWellDefined(DGModule).  It is exported for
low-level use when only the d^2 = 0 half of well-definedness needs to be
checked.

+------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)       |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : QuotientRing                         |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : isWellDefinedDifferential A          |
|                                          |
|o3 = true                                 |
+------------------------------------------+
|i4 : M = freeDGModule(A, {0})             |
|                                          |
|o4 = {Base ring => R                    } |
|      DG algebra => R[T   ..T   ]         |
|                       1,1   1,2          |
|                                       1  |
|      Natural module => (R[T   ..T   ])   |
|                            1,1   1,2     |
|      Generator degrees => {{0, 0}}       |
|      Differentials on gens => {0}        |
|                                          |
|o4 : DGModule                             |
+------------------------------------------+
|i5 : isWellDefinedDifferential M          |
|                                          |
|o5 = true                                 |
+------------------------------------------+

See also
========

  * Building DG algebras from existing DG algebras
    -- Base change, generator restriction,
    truncation, and targeted cycle-killing for DG algebras
  * Well-definedness, acyclicity, and quasi-isomorphism
    -- Predicates that
    check DG-theoretic conditions on DG types
  * isValidDGAlgebra -- Structural invariant check for
    a DG algebra
  * isWellDefined(DGAlgebra) -- Check that
    a DG algebra has correct structure and a differential that squares to zero
  * isWellDefined(DGModule) -- Check that a
    DG module has correct structure and that its differential squares to zero

Ways to use isWellDefinedDifferential:
======================================

  * "isWellDefinedDifferential(DGAlgebra)"
  * "isWellDefinedDifferential(DGModule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6797:0.

Low-level differential computations and validity checks -- Primitives behind DG algebra and DG module differentials
*******************************************************************************************************************

The methods documented here implement the raw computations that higher-level DG
algebra and DG module routines rely on. They split into three groups.

The first group -- see polyDifferential, and
polyDiffMonomial, -- applies the Leibniz rule directly to
elements of A.natural to produce the DG algebra differential.
polyDifferential(n, A) returns the per-degree matrix A_n --> A_{n-1} over the
base ring and caches it inside A; polyDifferential(A, f) applies d to a single
element by summing over its terms; polyDiffMonomial(A, m) is the monomial
kernel that powers both.

The second group -- see dgComplex, -- packages the per-degree
differentials of a DG algebra or DG module as a Complex (Complexes),
of free modules over the base ring. The result is cached
and invalidated by invalidateDGAlgebraCache.

The third group -- see isValidDGModule, and
isDGSubmodule, -- checks structural invariants. isValidDGModule
parallels isValidDGAlgebra, and confirms that the
required keys are present with the expected types; isDGSubmodule tests whether
a given inclusion matrix has d-closed image without performing the d-saturation
that dgSubmodule, would.

Finally, see getBoundaryPreimage,
lifts boundaries through the module differential, returning a preimage when one
exists and a residue otherwise.

See also
========

  * Basic operations on DG Algebras, --
    Outlines some basic operations on DG Algebras
  * Building DG modules, submodules, and quotients
    -- The DGModule / DGSubmodule /
    DGQuotientModule hierarchy and its constructors
  * Well-definedness, acyclicity, and quasi-isomorphism
    -- Predicates that
    check DG-theoretic conditions on DG types

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6849:0.

polyDifferential -- Matrix and element-level differentials of a DG algebra
**************************************************************************

  * Usage:
        d = polyDifferential(n, A)
        b = polyDifferential(A, f)
  * Inputs:
      * n, an integer (Macaulay2Doc), A homological degree.
      * A, an instance of the type DGAlgebra,
      * f, a ring element (Macaulay2Doc), An element of
        A.natural.
  * Outputs:
      * d, a matrix (Macaulay2Doc), The per-degree map A_n -->
        A_{n-1} over A.ring (first form).
      * b, a ring element (Macaulay2Doc), The image d(f) in
        A.natural (second form).

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

The two-argument form polyDifferential(n, A) returns the matrix of the DG
algebra differential in hom-degree n, expressed in the monomial basis of A_n
and A_{n-1}.  It is cached inside A and reused on subsequent calls; see
invalidateDGAlgebraCache, clears the cache.
Out-of-range degrees are handled uniformly: degree 0 gives the conventional
zero map R^1 --> R^0, and degrees past maxDegree A give zero maps of the
appropriate shape.

+------------------------------------------+
|i1 : R = QQ[x, y, z]                      |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,3  |
|      Differential => {x, y, z}           |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : d1 = polyDifferential(1, A)          |
|                                          |
|o3 = | x y z |                            |
|                                          |
|             1      3                     |
|o3 : Matrix R  <-- R                      |
+------------------------------------------+
|i4 : d2 = polyDifferential(2, A)          |
|                                          |
|o4 = {1} | -y -z 0  |                     |
|     {1} | x  0  -z |                     |
|     {1} | 0  x  y  |                     |
|                                          |
|             3      3                     |
|o4 : Matrix R  <-- R                      |
+------------------------------------------+
|i5 : d3 = polyDifferential(3, A)          |
|                                          |
|o5 = {2} | z  |                           |
|     {2} | -y |                           |
|     {2} | x  |                           |
|                                          |
|             3      1                     |
|o5 : Matrix R  <-- R                      |
+------------------------------------------+
|i6 : assert(d1 * d2 == 0)                 |
+------------------------------------------+
|i7 : assert(d2 * d3 == 0)                 |
+------------------------------------------+

The zero-degree map is the conventional R^1 --> R^0:

+---------------------------------------------------+
|i8 : R = QQ[x, y] / ideal(x^2, y^2)                |
|                                                   |
|o8 = R                                             |
|                                                   |
|o8 : QuotientRing                                  |
+---------------------------------------------------+
|i9 : A = koszulComplexDGA R                        |
|                                                   |
|o9 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,2           |
|      Differential => {x, y}                       |
|                                                   |
|o9 : DGAlgebra                                     |
+---------------------------------------------------+
|i10 : d0 = polyDifferential(0, A)                  |
|                                                   |
|o10 = 0                                            |
|                                                   |
|                    1                              |
|o10 : Matrix 0 <-- R                               |
+---------------------------------------------------+
|i11 : assert(source d0 == R^1 and target d0 == R^0)|
+---------------------------------------------------+

The element form polyDifferential(A, f) applies d to an arbitrary element by
summing over its monomial terms:

+-------------------------------------------+
|i12 : R = QQ[x, y] / ideal(x^2, y^2)       |
|                                           |
|o12 = R                                    |
|                                           |
|o12 : QuotientRing                         |
+-------------------------------------------+
|i13 : A = koszulComplexDGA R               |
|                                           |
|o13 = {Ring => R                          }|
|       Underlying algebra => R[T   ..T   ] |
|                                1,1   1,2  |
|       Differential => {x, y}              |
|                                           |
|o13 : DGAlgebra                            |
+-------------------------------------------+
|i14 : gs = gens A.natural                  |
|                                           |
|o14 = {T   , T   }                         |
|        1,1   1,2                          |
|                                           |
|o14 : List                                 |
+-------------------------------------------+
|i15 : polyDifferential(A, gs#0 * gs#1)     |
|                                           |
|o15 = - y*T    + x*T                       |
|           1,1      1,2                    |
|                                           |
|o15 : R[T   ..T   ]                        |
|         1,1   1,2                         |
+-------------------------------------------+

See also
========

  * Low-level differential computations and validity checks
    -- Primitives behind DG
    algebra and DG module differentials
  * polyDiffMonomial -- Leibniz rule on a single
    monomial of a DG algebra
  * diff(DGAlgebra,RingElement), --
    Apply the differential of a DGAlgebra to a ring element
  * invalidateDGAlgebraCache -- Discard cached
    derived data so that it is recomputed from scratch

Ways to use polyDifferential:
=============================

  * "polyDifferential(DGAlgebra,RingElement)"
  * "polyDifferential(ZZ,DGAlgebra)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6913:0.

polyDiffMonomial -- Leibniz rule on a single monomial of a DG algebra
*********************************************************************

  * Usage:
        b = polyDiffMonomial(A, m)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * m, a ring element (Macaulay2Doc), A monomial of
        A.natural (or the zero element).
  * Outputs:
      * b, a ring element (Macaulay2Doc), The image d(m) in
        A.natural.

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

polyDiffMonomial is the monomial kernel of the DG algebra differential.  It
splits m into its coefficient and its support powers and then applies the
graded Leibniz rule variable by variable, keeping track of the sign produced
when d passes an odd-degree generator.  The routine handles the zero element
without raising an exception, returning 0 in A.natural.

+----------------------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)                             |
|                                                                |
|o1 = R                                                          |
|                                                                |
|o1 : QuotientRing                                               |
+----------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                     |
|                                                                |
|o2 = {Ring => R                          }                      |
|      Underlying algebra => R[T   ..T   ]                       |
|                               1,1   1,2                        |
|      Differential => {x, y}                                    |
|                                                                |
|o2 : DGAlgebra                                                  |
+----------------------------------------------------------------+
|i3 : assert(polyDiffMonomial(A, 0_(A.natural)) == 0_(A.natural))|
+----------------------------------------------------------------+
|i4 : gs = gens A.natural                                        |
|                                                                |
|o4 = {T   , T   }                                               |
|       1,1   1,2                                                |
|                                                                |
|o4 : List                                                       |
+----------------------------------------------------------------+
|i5 : polyDiffMonomial(A, gs#0 * gs#1)                           |
|                                                                |
|o5 = - y*T    + x*T                                             |
|          1,1      1,2                                          |
|                                                                |
|o5 : R[T   ..T   ]                                              |
|        1,1   1,2                                               |
+----------------------------------------------------------------+

On a two-variable Koszul generator product, the Leibniz rule gives d(T_1 T_2) =
d(T_1) T_2 - T_1 d(T_2) = x T_2 - y T_1:

+-----------------------------------------+
|i6 : r = polyDiffMonomial(A, gs#0 * gs#1)|
|                                         |
|o6 = - y*T    + x*T                      |
|          1,1      1,2                   |
|                                         |
|o6 : R[T   ..T   ]                       |
|        1,1   1,2                        |
+-----------------------------------------+
|i7 : assert(r == x * gs#1 - y * gs#0)    |
+-----------------------------------------+

See also
========

  * Low-level differential computations and validity checks
    -- Primitives behind DG
    algebra and DG module differentials
  * polyDifferential -- Matrix and element-level
    differentials of a DG algebra
  * diff(DGAlgebra,RingElement), --
    Apply the differential of a DGAlgebra to a ring element

Ways to use polyDiffMonomial:
=============================

  * "polyDiffMonomial(DGAlgebra,RingElement)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:6955:0.

dgComplex -- Package a DG algebra or DG module as a Complex of free base-ring modules
*************************************************************************************

  * Usage:
        C = dgComplex A
        C = dgComplex M
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * M, an instance of the type DGModule,
  * Outputs:
      * C, a complex (Complexes), A Complex (Complexes),
        of free A.ring-modules whose i-th module is A_i
        (resp.\ M_i) and whose differential is polyDifferential (resp.\ See
        moduleDifferential).

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

dgComplex assembles the per-degree differentials of a DG algebra or DG module
into a single Complex (Complexes), object.  The result is cached
on the input; calling dgComplex again returns exactly the same complex, and
invalidateDGAlgebraCache, clears the cache so
that the next call rebuilds the complex.

+--------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)         |
|                                            |
|o1 = R                                      |
|                                            |
|o1 : QuotientRing                           |
+--------------------------------------------+
|i2 : A = koszulComplexDGA R                 |
|                                            |
|o2 = {Ring => R                          }  |
|      Underlying algebra => R[T   ..T   ]   |
|                               1,1   1,2    |
|      Differential => {x, y}                |
|                                            |
|o2 : DGAlgebra                              |
+--------------------------------------------+
|i3 : C1 = dgComplex A                       |
|                                            |
|      1      2      1                       |
|o3 = R  <-- R  <-- R                        |
|                                            |
|     0      1      2                        |
|                                            |
|o3 : Complex                                |
+--------------------------------------------+
|i4 : C2 = dgComplex A                       |
|                                            |
|      1      2      1                       |
|o4 = R  <-- R  <-- R                        |
|                                            |
|     0      1      2                        |
|                                            |
|o4 : Complex                                |
+--------------------------------------------+
|i5 : assert(C1 === C2)                      |
+--------------------------------------------+
|i6 : invalidateDGAlgebraCache A             |
|                                            |
|o6 = {Ring => R                          }  |
|      Underlying algebra => R[T   ..T   ]   |
|                               1,1   1,2    |
|      Differential => {x, y}                |
|                                            |
|o6 : DGAlgebra                              |
+--------------------------------------------+
|i7 : assert(not A.cache#?(symbol dgComplex))|
+--------------------------------------------+
|i8 : C3 = dgComplex A                       |
|                                            |
|      1      2      1                       |
|o8 = R  <-- R  <-- R                        |
|                                            |
|     0      1      2                        |
|                                            |
|o8 : Complex                                |
+--------------------------------------------+
|i9 : assert(instance(C3, Complex))          |
+--------------------------------------------+

When maxDegree is infinite -- for example on the acyclic closure of a
non-regular ring -- dgComplex truncates at a canonical finite bound so that a
Complex (Complexes), is always produced.

+----------------------------------------------+
|i10 : R = QQ[x, y] / ideal(x^2, y^2)          |
|                                              |
|o10 = R                                       |
|                                              |
|o10 : QuotientRing                            |
+----------------------------------------------+
|i11 : A = acyclicClosure(R, EndDegree => 2)   |
|                                              |
|o11 = {Ring => R                             }|
|       Underlying algebra => R[T   ..T   ]    |
|                                1,1   2,2     |
|       Differential => {x, y, x*T   , y*T   } |
|                                 1,1     1,2  |
|                                              |
|o11 : DGAlgebra                               |
+----------------------------------------------+
|i12 : assert(instance(dgComplex A, Complex))  |
+----------------------------------------------+

The DG module form is parallel: it builds the complex whose terms are M_i and
whose differentials are the maps returned by moduleDifferential.

+------------------------------------------+
|i13 : R = QQ[x, y] / ideal(x^2, y^2)      |
|                                          |
|o13 = R                                   |
|                                          |
|o13 : QuotientRing                        |
+------------------------------------------+
|i14 : KM = koszulComplexDGM R^1           |
|                                          |
|o14 = {Base ring => R                    }|
|       DG algebra => R[T   ..T   ]        |
|                        1,1   1,2         |
|                                        1 |
|       Natural module => (R[T   ..T   ])  |
|                             1,1   1,2    |
|       Generator degrees => {{0, 0}}      |
|       Differentials on gens => {0}       |
|                                          |
|o14 : DGModule                            |
+------------------------------------------+
|i15 : D1 = dgComplex KM                   |
|                                          |
|       1      2      1                    |
|o15 = R  <-- R  <-- R                     |
|                                          |
|      0      1      2                     |
|                                          |
|o15 : Complex                             |
+------------------------------------------+
|i16 : D2 = dgComplex KM                   |
|                                          |
|       1      2      1                    |
|o16 = R  <-- R  <-- R                     |
|                                          |
|      0      1      2                     |
|                                          |
|o16 : Complex                             |
+------------------------------------------+
|i17 : assert(D1 === D2)                   |
+------------------------------------------+

See also
========

  * Low-level differential computations and validity checks
    -- Primitives behind DG
    algebra and DG module differentials
  * polyDifferential -- Matrix and element-level
    differentials of a DG algebra
  * moduleDifferential -- The hom-degree-n
    differential of a DG module as a matrix over the base ring
  * invalidateDGAlgebraCache -- Discard cached
    derived data so that it is recomputed from scratch
  * toComplex -- Converts a DGAlgebra to a Complex

Ways to use dgComplex:
======================

  * "dgComplex(DGAlgebra)"
  * "dgComplex(DGModule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7019:0.

isValidDGModule -- Structural-invariant check on a DG module
************************************************************

  * Usage:
        b = isValidDGModule M
  * Inputs:
      * M, an instance of the type DGModule,
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), true if the stored
        DGModule has all required keys with the expected types; false
        otherwise.

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

isValidDGModule parallels isValidDGAlgebra,: it
confirms that M carries the keys dgAlgebra, ring, natural, Degrees, and diff
with the expected types, that the referenced DGAlgebra is itself structurally
valid, and that the generator-degree list has the same length as the
differential list.  It does not verify the semantic property d_M^2 = 0; that is
the job of isWellDefinedDifferential, and the
two together are what the user-facing isWellDefined(DGModule),
calls.

+-----------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)      |
|                                         |
|o1 = R                                   |
|                                         |
|o1 : QuotientRing                        |
+-----------------------------------------+
|i2 : KM = koszulComplexDGM R^1           |
|                                         |
|o2 = {Base ring => R                    }|
|      DG algebra => R[T   ..T   ]        |
|                       1,1   1,2         |
|                                       1 |
|      Natural module => (R[T   ..T   ])  |
|                            1,1   1,2    |
|      Generator degrees => {{0, 0}}      |
|      Differentials on gens => {0}       |
|                                         |
|o2 : DGModule                            |
+-----------------------------------------+
|i3 : assert(isValidDGModule KM)          |
+-----------------------------------------+

See also
========

  * Low-level differential computations and validity checks
    -- Primitives behind DG
    algebra and DG module differentials
  * Well-definedness, acyclicity, and quasi-isomorphism
    -- Predicates that
    check DG-theoretic conditions on DG types
  * isValidDGAlgebra -- Structural invariant check for
    a DG algebra
  * isWellDefinedDifferential -- Semantic
    check that d^2 = 0 for a DG algebra or DG module
  * isWellDefined(DGModule) -- Check that a
    DG module has correct structure and that its differential squares to zero

Ways to use isValidDGModule:
============================

  * "isValidDGModule(DGModule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7058:0.

isDGSubmodule -- Test whether the image of an inclusion matrix is d-closed
**************************************************************************

  * Usage:
        b = isDGSubmodule(M, incMat)
  * Inputs:
      * M, an instance of the type DGModule,
      * incMat, a matrix (Macaulay2Doc), A matrix whose target is
        M.natural.
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), true if the column
        span of incMat is closed under the differential of M; false otherwise.

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

isDGSubmodule checks whether a matrix of candidate generators spans a DG
submodule: it assembles d_M applied column-wise and then verifies that the
result lies in the column span of incMat via a single // solve.  Unlike
dgSubmodule, it does not saturate: a submodule that is not
d-closed is reported as such rather than enlarged.  The empty matrix is always
d-closed.

+-----------------------------------------------------------------+
|i1 : R = ZZ/101[x]                                               |
|                                                                 |
|o1 = R                                                           |
|                                                                 |
|o1 : PolynomialRing                                              |
+-----------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                      |
|                                                                 |
|o2 = {Ring => R                    }                             |
|      Underlying algebra => R[T   ]                              |
|                               1,1                               |
|      Differential => {x}                                        |
|                                                                 |
|o2 : DGAlgebra                                                   |
+-----------------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                                 |
|                                                                 |
|o3 = {Base ring => R                       }                     |
|      DG algebra => R[T   ]                                      |
|                       1,1                                       |
|                                 2                               |
|      Natural module => (R[T   ])                                |
|                            1,1                                  |
|      Generator degrees => {{0, 0}, {1, 0}}                      |
|      Differentials on gens => {0, 0}                            |
|                                                                 |
|o3 : DGModule                                                    |
+-----------------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)         |
|                                                                 |
|o4 = {| 1 |, | 0 |}                                              |
|      | 0 |  | 1 |                                               |
|                                                                 |
|o4 : List                                                        |
+-----------------------------------------------------------------+
|i5 : setDiff(M, {0, x * natGens#0})                              |
|                                                                 |
|o5 = {Base ring => R                       }                     |
|      DG algebra => R[T   ]                                      |
|                       1,1                                       |
|                                 2                               |
|      Natural module => (R[T   ])                                |
|                            1,1                                  |
|      Generator degrees => {{0, 0}, {1, 0}}                      |
|      Differentials on gens => {0, | x |}                        |
|                                   | 0 |                         |
|                                                                 |
|o5 : DGModule                                                    |
+-----------------------------------------------------------------+
|i6 : idM = identityDGModuleMap M                                 |
|                                                                 |
|                         2                                       |
|o6 = {Source => (R[T   ])      }                                 |
|                    1,1                                          |
|                         2                                       |
|      Target => (R[T   ])                                        |
|                    1,1                                          |
|      Natural => {0, 0} | 1 0 |                                  |
|                 {1, 0} | 0 1 |                                  |
|                                                                 |
|o6 : DGModuleMap                                                 |
+-----------------------------------------------------------------+
|i7 : imF = image idM                                             |
|                                                                 |
|o7 = DGSubmodule of ambient DGModule                             |
|     Degrees  => {{0, 0}, {1, 0}}                                |
|                          2                                      |
|     natural  => (R[T   ])                                       |
|                     1,1                                         |
|     inclusion => {0, 0} | 1 0 |                                 |
|                  {1, 0} | 0 1 |                                 |
|                                                                 |
|o7 : DGSubmodule                                                 |
+-----------------------------------------------------------------+
|i8 : assert(isDGSubmodule(target idM, (inclusion imF).natural))  |
+-----------------------------------------------------------------+
|i9 : kerF = kernel idM                                           |
|                                                                 |
|o9 = DGSubmodule of ambient DGModule                             |
|     Degrees  => {}                                              |
|     natural  => 0                                               |
|     inclusion => 0                                              |
|                                                                 |
|o9 : DGSubmodule                                                 |
+-----------------------------------------------------------------+
|i10 : assert(isDGSubmodule(source idM, (inclusion kerF).natural))|
+-----------------------------------------------------------------+

See also
========

  * Low-level differential computations and validity checks
    -- Primitives behind DG
    algebra and DG module differentials
  * dgSubmodule -- Construct a d-closed submodule of a DG
    module
  * image(DGModuleMap) -- Image of a DG module
    map as a DG submodule of its target
  * kernel(DGModuleMap) -- Kernel of a DG
    module map as a DG submodule of its source

Ways to use isDGSubmodule:
==========================

  * "isDGSubmodule(DGModule,Matrix)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7103:0.

getBoundaryPreimage(DGModule,Vector) -- Lift a boundary in a DG module to a preimage under the differential
***********************************************************************************************************

  * Function: getBoundaryPreimage,
  * Usage:
        (lifted, myLift) = getBoundaryPreimage(M, b)
  * Inputs:
      * M, an instance of the type DGModule, A free DG module
        over a DGAlgebra.
      * b, a vector (Macaulay2Doc), A homogeneous element of
        M.natural.
  * Outputs:
      * seq, a sequence (Macaulay2Doc), A pair (lifted,
        myLift).  If lifted is true, then myLift is an element with d_M(myLift)
        = b; otherwise myLift is the residue b - d_M(liftAttempt), which
        records how far b fails to be a boundary.

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

getBoundaryPreimage for DG modules is the module analogue of
getBoundaryPreimage(DGAlgebra,RingElement),: it attempts
to solve d_M(x) = b for x, using the matrix moduleDifferential(homDegree(b) +
1, M) and a single // solve.  Over a general ring such a solve may fail to find
a preimage even when one exists, so a true answer is a guarantee but a false
answer only says "the particular preimage candidate we tried left a residue".
The returned residue is b - d_M(liftAttempt).

+--------------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)                     |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : QuotientRing                                       |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                          }              |
|      Underlying algebra => R[T   ..T   ]               |
|                               1,1   1,2                |
|      Differential => {x, y}                            |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                        |
|                                                        |
|o3 = {Base ring => R                       }            |
|      DG algebra => R[T   ..T   ]                       |
|                       1,1   1,2                        |
|                                       2                |
|      Natural module => (R[T   ..T   ])                 |
|                            1,1   1,2                   |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, 0}                   |
|                                                        |
|o3 : DGModule                                           |
+--------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                        |
|o4 = {| 1 |, | 0 |}                                     |
|      | 0 |  | 1 |                                      |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : setDiff(M, {0, x * natGens#0})                     |
|                                                        |
|o5 = {Base ring => R                       }            |
|      DG algebra => R[T   ..T   ]                       |
|                       1,1   1,2                        |
|                                       2                |
|      Natural module => (R[T   ..T   ])                 |
|                            1,1   1,2                   |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, | x |}               |
|                                   | 0 |                |
|                                                        |
|o5 : DGModule                                           |
+--------------------------------------------------------+
|i6 : b = x * natGens#0                                  |
|                                                        |
|o6 = | x |                                              |
|     | 0 |                                              |
|                                                        |
|                    2                                   |
|o6 : (R[T   ..T   ])                                    |
|         1,1   1,2                                      |
+--------------------------------------------------------+
|i7 : (ok, pre) = getBoundaryPreimage(M, b)              |
|                                                        |
|o7 = (true, | T_(1,1) |)                                |
|            |    0    |                                 |
|                                                        |
|o7 : Sequence                                           |
+--------------------------------------------------------+
|i8 : assert(ok === true)                                |
+--------------------------------------------------------+
|i9 : assert(diff(M, pre) == b)                          |
+--------------------------------------------------------+

On a non-boundary, the first coordinate is false and the second coordinate
records the residue:

+-------------------------------------------------------+
|i10 : M2 = freeDGModule(A, {0})                        |
|                                                       |
|o10 = {Base ring => R                    }             |
|       DG algebra => R[T   ..T   ]                     |
|                        1,1   1,2                      |
|                                        1              |
|       Natural module => (R[T   ..T   ])               |
|                             1,1   1,2                 |
|       Generator degrees => {{0, 0}}                   |
|       Differentials on gens => {0}                    |
|                                                       |
|o10 : DGModule                                         |
+-------------------------------------------------------+
|i11 : ng2 = apply(rank M2.natural, i -> (M2.natural)_i)|
|                                                       |
|o11 = {| 1 |}                                          |
|                                                       |
|o11 : List                                             |
+-------------------------------------------------------+
|i12 : (ok2, residue) = getBoundaryPreimage(M2, ng2#0)  |
|                                                       |
|o12 = (false, | 1 |)                                   |
|                                                       |
|o12 : Sequence                                         |
+-------------------------------------------------------+
|i13 : assert(ok2 === false)                            |
+-------------------------------------------------------+
|i14 : assert(residue != 0)                             |
+-------------------------------------------------------+

See also
========

  * Low-level differential computations and validity checks
    -- Primitives behind DG
    algebra and DG module differentials
  * getBoundaryPreimage(DGModule,List)
    -- Lift a list of boundaries
    sharing a hom-degree through the module differential
  * getBoundaryPreimage -- Attempt to find a
    preimage of a boundary under the differential of a DGAlgebra.
  * moduleDifferential -- The hom-degree-n
    differential of a DG module as a matrix over the base ring
  * homologyClass -- Computes the element of the homology
    algebra corresponding to a cycle in a DGAlgebra.

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

  * getBoundaryPreimage(DGModule,Vector)
    -- Lift a boundary in a DG
    module to a preimage under the differential
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7162:0.

getBoundaryPreimage(DGModule,List) -- Lift a list of boundaries sharing a hom-degree through the module differential
********************************************************************************************************************

  * Function: getBoundaryPreimage,
  * Usage:
        (lifted, lifts) = getBoundaryPreimage(M, boundaryList)
  * Inputs:
      * M, an instance of the type DGModule, A free DG module
        over a DGAlgebra.
      * boundaryList, a list (Macaulay2Doc), A list of elements of
        M.natural, each either 0 or homogeneous of a common hom-degree.
  * Outputs:
      * seq, a sequence (Macaulay2Doc), A pair (lifted, lifts).
        If lifted is true, then lifts#i satisfies d_M(lifts#i) = boundaryList#i
        for every i; otherwise lifts is the list of per-entry residues.

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

The list form of getBoundaryPreimage(DGModule,Vector),
solves multiple preimage problems
in a single // call.  Zero entries are permitted and contribute zero columns;
all nonzero entries must share a hom-degree. When every boundary lifts, the
returned list preserves the order of boundaryList.

+-------------------------------------------------------------+
|i1 : R = QQ[x]                                               |
|                                                             |
|o1 = R                                                       |
|                                                             |
|o1 : PolynomialRing                                          |
+-------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                  |
|                                                             |
|o2 = {Ring => R                    }                         |
|      Underlying algebra => R[T   ]                          |
|                               1,1                           |
|      Differential => {x}                                    |
|                                                             |
|o2 : DGAlgebra                                               |
+-------------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                             |
|                                                             |
|o3 = {Base ring => R                       }                 |
|      DG algebra => R[T   ]                                  |
|                       1,1                                   |
|                                 2                           |
|      Natural module => (R[T   ])                            |
|                            1,1                              |
|      Generator degrees => {{0, 0}, {1, 0}}                  |
|      Differentials on gens => {0, 0}                        |
|                                                             |
|o3 : DGModule                                                |
+-------------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)     |
|                                                             |
|o4 = {| 1 |, | 0 |}                                          |
|      | 0 |  | 1 |                                           |
|                                                             |
|o4 : List                                                    |
+-------------------------------------------------------------+
|i5 : setDiff(M, {0, x * natGens#0})                          |
|                                                             |
|o5 = {Base ring => R                       }                 |
|      DG algebra => R[T   ]                                  |
|                       1,1                                   |
|                                 2                           |
|      Natural module => (R[T   ])                            |
|                            1,1                              |
|      Generator degrees => {{0, 0}, {1, 0}}                  |
|      Differentials on gens => {0, | x |}                    |
|                                   | 0 |                     |
|                                                             |
|o5 : DGModule                                                |
+-------------------------------------------------------------+
|i6 : b = x * natGens#0                                       |
|                                                             |
|o6 = | x |                                                   |
|     | 0 |                                                   |
|                                                             |
|              2                                              |
|o6 : (R[T   ])                                               |
|         1,1                                                 |
+-------------------------------------------------------------+
|i7 : (ok, lifts) = getBoundaryPreimage(M, {b, 0_(M.natural)})|
|                                                             |
|o7 = (true, {| T_(1,1) |, 0})                                |
|             |    0    |                                     |
|                                                             |
|o7 : Sequence                                                |
+-------------------------------------------------------------+
|i8 : assert(ok === true)                                     |
+-------------------------------------------------------------+
|i9 : assert(diff(M, lifts#0) == b)                           |
+-------------------------------------------------------------+
|i10 : assert(diff(M, lifts#1) == 0)                          |
+-------------------------------------------------------------+

See also
========

  * Low-level differential computations and validity checks
    -- Primitives behind DG
    algebra and DG module differentials
  * getBoundaryPreimage(DGModule,Vector)
    -- Lift a boundary in a DG
    module to a preimage under the differential
  * getBoundaryPreimage -- Attempt to find a
    preimage of a boundary under the differential of a DGAlgebra.
  * moduleDifferential -- The hom-degree-n
    differential of a DG module as a matrix over the base ring

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

  * getBoundaryPreimage(DGModule,List)
    -- Lift a list of boundaries
    sharing a hom-degree through the module differential
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7207:0.

Accessors and cache management -- Reading state out of a DG algebra or DG module and maintaining its caches
***********************************************************************************************************

A DGAlgebra, or DGModule, stores its defining
data in a small collection of keys -- the base ring, the graded-commutative
algebra, the generator degrees, and the list of generator differentials --
together with a cache of derived information (per-degree differential matrices,
homology, the homology algebra, a Complex (Complexes),
presentation).  This page collects the two groups of utilities that manage that
state.

The first group -- see underlyingRing,
underlyingAlgebra, differential, and
generatorDegrees, -- returns the four defining
ingredients.  Because both DG algebras and DG modules carry the same names,
code can remain agnostic about which one it is handling.

The second group -- see ensureDGAlgebraCaches, and
invalidateDGAlgebraCache, -- maintains the
cache sub-tables.  ensureDGAlgebraCaches is idempotent and guarantees that the
standard cache keys are present with the expected types; see
invalidateDGAlgebraCache, wipes every cached computed
value so that the next call recomputes from scratch.  Routines such as
setDiff, that mutate the differential call
invalidateDGAlgebraCache, internally so that stale
homology and stale differential matrices are never served.

See also
========

  * Basic operations on DG Algebras, --
    Outlines some basic operations on DG Algebras
  * Building DG modules, submodules, and quotients
    -- The DGModule / DGSubmodule /
    DGQuotientModule hierarchy and its constructors
  * Low-level differential computations and validity checks
    -- Primitives behind DG
    algebra and DG module differentials

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7253:0.

underlyingRing -- The commutative base ring of a DG algebra or DG module
************************************************************************

  * Usage:
        S = underlyingRing A
        S = underlyingRing M
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * M, an instance of the type DGModule,
  * Outputs:
      * S, a ring (Macaulay2Doc), The commutative base ring A.ring
        or M.ring over which the DG structure is defined.

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

underlyingRing returns the base ring.  This is the ring R in the DG algebra A =
R\langle T_1, T_2, \ldots \rangle or the DG module M, and it is the ring over
which every matrix returned by polyDifferential, or
moduleDifferential, is built.

+------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)       |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : QuotientRing                         |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : assert(underlyingRing A === R)       |
+------------------------------------------+
+-----------------------------------------+
|i4 : M = koszulComplexDGM R^1            |
|                                         |
|o4 = {Base ring => R                    }|
|      DG algebra => R[T   ..T   ]        |
|                       1,1   1,2         |
|                                       1 |
|      Natural module => (R[T   ..T   ])  |
|                            1,1   1,2    |
|      Generator degrees => {{0, 0}}      |
|      Differentials on gens => {0}       |
|                                         |
|o4 : DGModule                            |
+-----------------------------------------+
|i5 : assert(underlyingRing M === R)      |
+-----------------------------------------+

See also
========

  * Accessors and cache management, --
    Reading state out of a DG algebra or DG module and maintaining its caches
  * underlyingAlgebra -- The graded-commutative
    algebra carrying the DG structure
  * differential -- The list of generator differentials
    stored in a DG algebra or DG module
  * generatorDegrees -- The hom-degrees (and optional
    internal degrees) of the DG generators

Ways to use underlyingRing:
===========================

  * "underlyingRing(DGAlgebra)"
  * "underlyingRing(DGModule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7291:0.

underlyingAlgebra -- The graded-commutative algebra carrying the DG structure
*****************************************************************************

  * Usage:
        N = underlyingAlgebra A
        N = underlyingAlgebra M
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * M, an instance of the type DGModule,
  * Outputs:
      * N, a ring (Macaulay2Doc), The graded-commutative ring
        A.natural (the DG algebra's own ring) or, for a DG module, the graded
        free module M.natural (as a Module (Macaulay2Doc), over
        A.natural).

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

For a DGAlgebra, underlyingAlgebra returns the
graded-commutative ring A.natural -- the ring whose elements one manipulates
when writing polynomials in the DG generators.  For a DGModule,
it returns the underlying A.natural-module M.natural on which the differential
acts.  In both cases the result is what you typically use before referring to
DG generators by name.

+----------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)           |
|                                              |
|o1 = R                                        |
|                                              |
|o1 : QuotientRing                             |
+----------------------------------------------+
|i2 : A = koszulComplexDGA R                   |
|                                              |
|o2 = {Ring => R                          }    |
|      Underlying algebra => R[T   ..T   ]     |
|                               1,1   1,2      |
|      Differential => {x, y}                  |
|                                              |
|o2 : DGAlgebra                                |
+----------------------------------------------+
|i3 : assert(underlyingAlgebra A === A.natural)|
+----------------------------------------------+
|i4 : numgens underlyingAlgebra A              |
|                                              |
|o4 = 2                                        |
+----------------------------------------------+
+----------------------------------------------+
|i5 : M = koszulComplexDGM R^1                 |
|                                              |
|o5 = {Base ring => R                    }     |
|      DG algebra => R[T   ..T   ]             |
|                       1,1   1,2              |
|                                       1      |
|      Natural module => (R[T   ..T   ])       |
|                            1,1   1,2         |
|      Generator degrees => {{0, 0}}           |
|      Differentials on gens => {0}            |
|                                              |
|o5 : DGModule                                 |
+----------------------------------------------+
|i6 : assert(underlyingAlgebra M === M.natural)|
+----------------------------------------------+

See also
========

  * Accessors and cache management, --
    Reading state out of a DG algebra or DG module and maintaining its caches
  * underlyingRing -- The commutative base ring of a DG
    algebra or DG module
  * differential -- The list of generator differentials
    stored in a DG algebra or DG module
  * generatorDegrees -- The hom-degrees (and optional
    internal degrees) of the DG generators

Ways to use underlyingAlgebra:
==============================

  * "underlyingAlgebra(DGAlgebra)"
  * "underlyingAlgebra(DGModule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7335:0.

differential -- The list of generator differentials stored in a DG algebra or DG module
***************************************************************************************

  * Usage:
        d = differential A
        d = differential M
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * M, an instance of the type DGModule,
  * Outputs:
      * d, a list (Macaulay2Doc), The stored list of differentials:
        for a DGAlgebra, one element of A.natural per DG
        generator; for a DGModule, one element of M.natural
        per natural generator.

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

differential returns the raw list of generator differentials that was installed
by setDiff.  The i-th entry is the image of the i-th DG
generator under d, and every other differential is computed from it by
linearity and the graded Leibniz rule.

+-----------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)                  |
|                                                     |
|o1 = R                                               |
|                                                     |
|o1 : QuotientRing                                    |
+-----------------------------------------------------+
|i2 : A = koszulComplexDGA R                          |
|                                                     |
|o2 = {Ring => R                          }           |
|      Underlying algebra => R[T   ..T   ]            |
|                               1,1   1,2             |
|      Differential => {x, y}                         |
|                                                     |
|o2 : DGAlgebra                                       |
+-----------------------------------------------------+
|i3 : differential A                                  |
|                                                     |
|o3 = map (R[T   ..T   ], R[T   ..T   ], {x, y, x, y})|
|             1,1   1,2      1,1   1,2                |
|                                                     |
|o3 : RingMap R[T   ..T   ] <-- R[T   ..T   ]         |
|                1,1   1,2         1,1   1,2          |
+-----------------------------------------------------+
|i4 : assert(differential A === A.diff)               |
+-----------------------------------------------------+
+-----------------------------------------+
|i5 : M = koszulComplexDGM R^1            |
|                                         |
|o5 = {Base ring => R                    }|
|      DG algebra => R[T   ..T   ]        |
|                       1,1   1,2         |
|                                       1 |
|      Natural module => (R[T   ..T   ])  |
|                            1,1   1,2    |
|      Generator degrees => {{0, 0}}      |
|      Differentials on gens => {0}       |
|                                         |
|o5 : DGModule                            |
+-----------------------------------------+
|i6 : differential M                      |
|                                         |
|o6 = {0}                                 |
|                                         |
|o6 : List                                |
+-----------------------------------------+

See also
========

  * Accessors and cache management, --
    Reading state out of a DG algebra or DG module and maintaining its caches
  * setDiff -- Install or replace the differential on a DG
    algebra
  * polyDifferential -- Matrix and element-level
    differentials of a DG algebra
  * moduleDifferential -- The hom-degree-n
    differential of a DG module as a matrix over the base ring

Ways to use differential:
=========================

  * "differential(DGAlgebra)"
  * "differential(DGModule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7376:0.

generatorDegrees -- The hom-degrees (and optional internal degrees) of the DG generators
****************************************************************************************

  * Usage:
        degs = generatorDegrees A
        degs = generatorDegrees M
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * M, an instance of the type DGModule,
  * Outputs:
      * degs, a list (Macaulay2Doc), A list of degree vectors, one
        per DG generator (for a DG algebra) or one per natural generator (for a
        DG module).

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

generatorDegrees returns the degree data that was supplied at construction.
Each entry is a list whose first coordinate is the homological degree and whose
remaining coordinates record the internal (multi-)grading of the base ring.

+------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)       |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : QuotientRing                         |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : generatorDegrees A                   |
|                                          |
|o3 = {{1, 1}, {1, 1}}                     |
|                                          |
|o3 : List                                 |
+------------------------------------------+
+----------------------------------------------------+
|i4 : M = freeDGModule(A, {0, 1, 3})                 |
|                                                    |
|o4 = {Base ring => R                               }|
|      DG algebra => R[T   ..T   ]                   |
|                       1,1   1,2                    |
|                                       3            |
|      Natural module => (R[T   ..T   ])             |
|                            1,1   1,2               |
|      Generator degrees => {{0, 0}, {1, 0}, {3, 0}} |
|      Differentials on gens => {0, 0, 0}            |
|                                                    |
|o4 : DGModule                                       |
+----------------------------------------------------+
|i5 : generatorDegrees M                             |
|                                                    |
|o5 = {{0, 0}, {1, 0}, {3, 0}}                       |
|                                                    |
|o5 : List                                           |
+----------------------------------------------------+

See also
========

  * Accessors and cache management, --
    Reading state out of a DG algebra or DG module and maintaining its caches
  * underlyingRing -- The commutative base ring of a DG
    algebra or DG module
  * underlyingAlgebra -- The graded-commutative
    algebra carrying the DG structure
  * differential -- The list of generator differentials
    stored in a DG algebra or DG module

Ways to use generatorDegrees:
=============================

  * "generatorDegrees(DGAlgebra)"
  * "generatorDegrees(DGModule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7414:0.

ensureDGAlgebraCaches -- Guarantee that the standard cache sub-tables are present
*********************************************************************************

  * Usage:
        A = ensureDGAlgebraCaches A
        M = ensureDGAlgebraCaches M
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * M, an instance of the type DGModule,
  * Outputs:
      * an instance of the type DGAlgebra, or an instance of
        the type DGModule, The same object, with any missing
        standard cache sub-table created (the method mutates the input and
        returns it).

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

ensureDGAlgebraCaches is idempotent: it creates the cache sub-tables that the
rest of the package expects (the homology, homologyAlgebra, and diffs
sub-tables for a DG algebra; the diffs sub-table for a DG module), and leaves
any that already exist untouched.  Code that reads from the cache can call this
method once up front and thereafter assume the sub-tables are present with the
right types, rather than defensively checking each access.

+------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)       |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : QuotientRing                         |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : ensureDGAlgebraCaches A              |
|                                          |
|o3 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o3 : DGAlgebra                            |
+------------------------------------------+
|i4 : assert(instance(A.cache, CacheTable))|
+------------------------------------------+
|i5 : ensureDGAlgebraCaches A              |
|                                          |
|o5 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o5 : DGAlgebra                            |
+------------------------------------------+
|i6 : assert(instance(A.cache, CacheTable))|
+------------------------------------------+
+-------------------------------------------+
|i7 : KM = koszulComplexDGM R^1             |
|                                           |
|o7 = {Base ring => R                    }  |
|      DG algebra => R[T   ..T   ]          |
|                       1,1   1,2           |
|                                       1   |
|      Natural module => (R[T   ..T   ])    |
|                            1,1   1,2      |
|      Generator degrees => {{0, 0}}        |
|      Differentials on gens => {0}         |
|                                           |
|o7 : DGModule                              |
+-------------------------------------------+
|i8 : ensureDGAlgebraCaches KM              |
|                                           |
|o8 = {Base ring => R                    }  |
|      DG algebra => R[T   ..T   ]          |
|                       1,1   1,2           |
|                                       1   |
|      Natural module => (R[T   ..T   ])    |
|                            1,1   1,2      |
|      Generator degrees => {{0, 0}}        |
|      Differentials on gens => {0}         |
|                                           |
|o8 : DGModule                              |
+-------------------------------------------+
|i9 : assert(instance(KM.cache, CacheTable))|
+-------------------------------------------+

See also
========

  * Accessors and cache management, --
    Reading state out of a DG algebra or DG module and maintaining its caches
  * invalidateDGAlgebraCache -- Discard cached
    derived data so that it is recomputed from scratch

Ways to use ensureDGAlgebraCaches:
==================================

  * "ensureDGAlgebraCaches(DGAlgebra)"
  * "ensureDGAlgebraCaches(DGModule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7459:0.

invalidateDGAlgebraCache -- Discard cached derived data so that it is recomputed from scratch
*********************************************************************************************

  * Usage:
        A = invalidateDGAlgebraCache A
        M = invalidateDGAlgebraCache M
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * M, an instance of the type DGModule,
  * Outputs:
      * an instance of the type DGAlgebra, or an instance of
        the type DGModule, The same object with every cached
        derived value cleared (the method mutates the input and returns it).

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

invalidateDGAlgebraCache wipes every cache entry that records a value derived
from the differential: per-degree differential matrices, per-degree homology,
the homology algebra, and any Complex (Complexes), or block-diff
summary cached by dgComplex, or displayBlockDiff.
The cache sub-tables themselves are recreated empty, so
subsequent lookups recompute the values rather than returning stale results.
Routines that mutate the differential (most notably setDiff)
call this function internally.

+--------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)         |
|                                            |
|o1 = R                                      |
|                                            |
|o1 : QuotientRing                           |
+--------------------------------------------+
|i2 : A = koszulComplexDGA R                 |
|                                            |
|o2 = {Ring => R                          }  |
|      Underlying algebra => R[T   ..T   ]   |
|                               1,1   1,2    |
|      Differential => {x, y}                |
|                                            |
|o2 : DGAlgebra                              |
+--------------------------------------------+
|i3 : C1 = dgComplex A                       |
|                                            |
|      1      2      1                       |
|o3 = R  <-- R  <-- R                        |
|                                            |
|     0      1      2                        |
|                                            |
|o3 : Complex                                |
+--------------------------------------------+
|i4 : invalidateDGAlgebraCache A             |
|                                            |
|o4 = {Ring => R                          }  |
|      Underlying algebra => R[T   ..T   ]   |
|                               1,1   1,2    |
|      Differential => {x, y}                |
|                                            |
|o4 : DGAlgebra                              |
+--------------------------------------------+
|i5 : assert(not A.cache#?(symbol dgComplex))|
+--------------------------------------------+
|i6 : C2 = dgComplex A                       |
|                                            |
|      1      2      1                       |
|o6 = R  <-- R  <-- R                        |
|                                            |
|     0      1      2                        |
|                                            |
|o6 : Complex                                |
+--------------------------------------------+
|i7 : assert(instance(C2, Complex))          |
+--------------------------------------------+
+----------------------------------------------+
|i8 : KM = koszulComplexDGM R^1                |
|                                              |
|o8 = {Base ring => R                    }     |
|      DG algebra => R[T   ..T   ]             |
|                       1,1   1,2              |
|                                       1      |
|      Natural module => (R[T   ..T   ])       |
|                            1,1   1,2         |
|      Generator degrees => {{0, 0}}           |
|      Differentials on gens => {0}            |
|                                              |
|o8 : DGModule                                 |
+----------------------------------------------+
|i9 : D1 = dgComplex KM                        |
|                                              |
|      1      2      1                         |
|o9 = R  <-- R  <-- R                          |
|                                              |
|     0      1      2                          |
|                                              |
|o9 : Complex                                  |
+----------------------------------------------+
|i10 : invalidateDGAlgebraCache KM             |
|                                              |
|o10 = {Base ring => R                    }    |
|       DG algebra => R[T   ..T   ]            |
|                        1,1   1,2             |
|                                        1     |
|       Natural module => (R[T   ..T   ])      |
|                             1,1   1,2        |
|       Generator degrees => {{0, 0}}          |
|       Differentials on gens => {0}           |
|                                              |
|o10 : DGModule                                |
+----------------------------------------------+
|i11 : assert(not KM.cache#?(symbol dgComplex))|
+----------------------------------------------+
|i12 : D2 = dgComplex KM                       |
|                                              |
|       1      2      1                        |
|o12 = R  <-- R  <-- R                         |
|                                              |
|      0      1      2                         |
|                                              |
|o12 : Complex                                 |
+----------------------------------------------+
|i13 : assert(instance(D2, Complex))           |
+----------------------------------------------+

See also
========

  * Accessors and cache management, --
    Reading state out of a DG algebra or DG module and maintaining its caches
  * ensureDGAlgebraCaches -- Guarantee that the
    standard cache sub-tables are present
  * setDiff -- Install or replace the differential on a DG
    algebra
  * dgComplex -- Package a DG algebra or DG module as a
    Complex of free base-ring modules

Ways to use invalidateDGAlgebraCache:
=====================================

  * "invalidateDGAlgebraCache(DGAlgebra)"
  * "invalidateDGAlgebraCache(DGModule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7509:0.

DG module primitives and chain-complex export -- Installing differentials, reading degree data, and exporting to Complex
************************************************************************************************************************

This page collects the remaining DG module primitives (installing a
differential, asking for the largest hom-degree, reading off a per-degree
basis) together with the methods that export a DG algebra, DG module, DG module
map, or DG ideal to the ordinary Complex (Complexes), / see
ComplexMap (Complexes), world.

Installing a differential.  See setDiff(DGModule,List),
is the DG module analogue of
setDiff(DGAlgebra,List),: it records the image of each natural
generator under d_M and invalidates every cached derived value.

Reading degree data.  See maxDegree(DGModule), and
maxDegree(DGQuotientModule), report the
largest hom-degree present (or infinity if the underlying DG algebra has an
even-degree generator). See getBasis(ZZ,DGModule),
returns an A.ring-basis of the hom-degree-n piece
of M.natural.

Exporting to Complex (Complexes).  The toComplex,
family packages per-degree differentials as a plain Complex (Complexes),
of free base-ring modules; the toComplexMap,
family packages per-degree induced maps as a ComplexMap (Complexes).
Together they let the chain-level results of the DG
machinery be handed off to the rest of the Complexes,
package.

Block-diagonal display.  See displayBlockDiff, prints the
per-internal-multidegree block decomposition of a DG algebra differential at a
given homological degree, convenient for inspecting the acyclic closure of a
multigraded quotient.

See also
========

  * Basic operations on DG Algebras, --
    Outlines some basic operations on DG Algebras
  * Building DG modules, submodules, and quotients
    -- The DGModule / DGSubmodule /
    DGQuotientModule hierarchy and its constructors
  * Low-level differential computations and validity checks
    -- Primitives behind DG
    algebra and DG module differentials

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7568:0.

setDiff(DGModule,List) -- Install the list of generator differentials on a free DG module
*****************************************************************************************

  * Function: setDiff,
  * Usage:
        setDiff(M, diffList)
  * Inputs:
      * M, an instance of the type DGModule, A free DG module
        (from freeDGModule).
      * diffList, a list (Macaulay2Doc), One entry per natural
        generator of M.  Each entry is a vector of M.natural (or 0, or a
        one-column matrix that will be folded into a vector).
  * Optional inputs (Macaulay2Doc),:
      * InitializeComplex, => ..., default value true, Install
        or replace the differential on a DG algebra
      * InitializeDegreeZeroHomology, => ..., default value
        true, Install or replace the differential on a DG algebra
  * Outputs:
      * an instance of the type DGModule, The same M, mutated
        to carry the new differentials.

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

setDiff is the DG module analogue of setDiff(DGAlgebra,List),:
it records the image of the i-th natural generator under the differential in
the i-th slot of M.diff, and clears every cached derived value so that later
calls to moduleDifferential, or homology (Macaulay2Doc),
will recompute from the newly installed data.  Only
free DG modules (those produced by freeDGModule) are
accepted; the list length must match the number of natural generators.

+--------------------------------------------------------+
|i1 : R = QQ[x]                                          |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                    }                    |
|      Underlying algebra => R[T   ]                     |
|                               1,1                      |
|      Differential => {x}                               |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                        |
|                                                        |
|o3 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, 0}                   |
|                                                        |
|o3 : DGModule                                           |
+--------------------------------------------------------+
|i4 : natGens = apply(rank M.natural, i -> (M.natural)_i)|
|                                                        |
|o4 = {| 1 |, | 0 |}                                     |
|      | 0 |  | 1 |                                      |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : setDiff(M, {0, x^2 * natGens#0})                   |
|                                                        |
|o5 = {Base ring => R                       }            |
|      DG algebra => R[T   ]                             |
|                       1,1                              |
|                                 2                      |
|      Natural module => (R[T   ])                       |
|                            1,1                         |
|      Generator degrees => {{0, 0}, {1, 0}}             |
|      Differentials on gens => {0, | x2 |}              |
|                                   |  0 |               |
|                                                        |
|o5 : DGModule                                           |
+--------------------------------------------------------+
|i6 : d1 = moduleDifferential(1, M)                      |
|                                                        |
|o6 = | x x2 |                                           |
|                                                        |
|             1      2                                   |
|o6 : Matrix R  <-- R                                    |
+--------------------------------------------------------+
|i7 : d2 = moduleDifferential(2, M)                      |
|                                                        |
|o7 = {1} | -x2 |                                        |
|     {0} | x   |                                        |
|                                                        |
|             2      1                                   |
|o7 : Matrix R  <-- R                                    |
+--------------------------------------------------------+
|i8 : assert(d1 * d2 == 0)                               |
+--------------------------------------------------------+

See also
========

  * DG module primitives and chain-complex export
    -- Installing differentials, reading degree data,
    and exporting to Complex
  * freeDGModule -- Construct a free DG module over a DG
    algebra
  * setDiff(DGAlgebra,List) -- Install or replace the
    differential on a DG algebra
  * moduleDifferential -- The hom-degree-n
    differential of a DG module as a matrix over the base ring
  * invalidateDGAlgebraCache -- Discard cached
    derived data so that it is recomputed from scratch

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

  * setDiff(DGModule,List) -- Install the
    list of generator differentials on a free DG module
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7613:0.

maxDegree(DGModule) -- Largest hom-degree present in a DG module
****************************************************************

  * Function: maxDegree,
  * Usage:
        n = maxDegree M
  * Inputs:
      * M, an instance of the type DGModule,
  * Outputs:
      * n, an integer (Macaulay2Doc), or an infinite number (Macaulay2Doc),
        maxDegree A + max(first d | d in
        M.Degrees) when A has finite max hom-degree; infinity otherwise.

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

maxDegree of a DG module combines the hom-degree bound of the ambient
DGAlgebra, with the largest hom-degree shift of a natural generator.
When the underlying DG algebra has an even-degree generator it has infinity as
its max degree, and so does every DG module over it.

+---------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)                |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : QuotientRing                                  |
+---------------------------------------------------+
|i2 : KM = koszulComplexDGM R^1                     |
|                                                   |
|o2 = {Base ring => R                    }          |
|      DG algebra => R[T   ..T   ]                  |
|                       1,1   1,2                   |
|                                       1           |
|      Natural module => (R[T   ..T   ])            |
|                            1,1   1,2              |
|      Generator degrees => {{0, 0}}                |
|      Differentials on gens => {0}                 |
|                                                   |
|o2 : DGModule                                      |
+---------------------------------------------------+
|i3 : assert(maxDegree KM == maxDegree KM.dgAlgebra)|
+---------------------------------------------------+
+--------------------------------------------+
|i4 : A = koszulComplexDGA R                 |
|                                            |
|o4 = {Ring => R                          }  |
|      Underlying algebra => R[T   ..T   ]   |
|                               1,1   1,2    |
|      Differential => {x, y}                |
|                                            |
|o4 : DGAlgebra                              |
+--------------------------------------------+
|i5 : M = freeDGModule(A, {0, 3})            |
|                                            |
|o5 = {Base ring => R                       }|
|      DG algebra => R[T   ..T   ]           |
|                       1,1   1,2            |
|                                       2    |
|      Natural module => (R[T   ..T   ])     |
|                            1,1   1,2       |
|      Generator degrees => {{0, 0}, {3, 0}} |
|      Differentials on gens => {0, 0}       |
|                                            |
|o5 : DGModule                               |
+--------------------------------------------+
|i6 : maxDegree M                            |
|                                            |
|o6 = 5                                      |
+--------------------------------------------+

See also
========

  * DG module primitives and chain-complex export
    -- Installing differentials, reading degree data,
    and exporting to Complex
  * maxDegree -- Computes the maximum homological degree of a
    DGAlgebra
  * maxDegree(DGQuotientModule), --
    Largest hom-degree present in a DG quotient module
  * maxDegree(DGAlgebra) -- Computes the maximum homological
    degree of a DGAlgebra

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

  * maxDegree(DGModule) -- Largest hom-degree
    present in a DG module
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7650:0.

maxDegree(DGQuotientModule) -- Largest hom-degree present in a DG quotient module
*********************************************************************************

  * Function: maxDegree,
  * Usage:
        n = maxDegree Q
  * Inputs:
      * Q, an instance of the type DGQuotientModule,
  * Outputs:
      * n, an integer (Macaulay2Doc), or an infinite number (Macaulay2Doc),
        The maxDegree of the ambient DG module
        Q.ambient.

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

Passing a DG quotient module to maxDegree, returns the max
hom-degree of its ambient DG module.  Because taking a quotient cannot
introduce elements of higher hom-degree than are already in the ambient, the
ambient's bound is valid for the quotient.  The value is what
toComplex(DGQuotientModule), and
toComplexMap(DGModuleMap), use to decide where
to truncate when no EndDegree, is supplied.

+--------------------------------------------+
|i1 : R = ZZ/101[x]                          |
|                                            |
|o1 = R                                      |
|                                            |
|o1 : PolynomialRing                         |
+--------------------------------------------+
|i2 : A = koszulComplexDGA R                 |
|                                            |
|o2 = {Ring => R                    }        |
|      Underlying algebra => R[T   ]         |
|                               1,1          |
|      Differential => {x}                   |
|                                            |
|o2 : DGAlgebra                              |
+--------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})            |
|                                            |
|o3 = {Base ring => R                       }|
|      DG algebra => R[T   ]                 |
|                       1,1                  |
|                                 2          |
|      Natural module => (R[T   ])           |
|                            1,1             |
|      Generator degrees => {{0, 0}, {1, 0}} |
|      Differentials on gens => {0, 0}       |
|                                            |
|o3 : DGModule                               |
+--------------------------------------------+
|i4 : z = zeroDGModuleMap(M, M)              |
|                                            |
|                         2                  |
|o4 = {Source => (R[T   ]) }                 |
|                    1,1                     |
|                         2                  |
|      Target => (R[T   ])                   |
|                    1,1                     |
|      Natural => 0                          |
|                                            |
|o4 : DGModuleMap                            |
+--------------------------------------------+
|i5 : Q = cokernel z                         |
|                                            |
|o5 = DGQuotientModule Q = M / S             |
|                          2                 |
|     Q.natural = (R[T   ])                  |
|                     1,1                    |
|     Degrees   = {{0, 0}, {1, 0}}           |
|                                            |
|o5 : DGQuotientModule                       |
+--------------------------------------------+
|i6 : assert(maxDegree Q == maxDegree M)     |
+--------------------------------------------+

See also
========

  * DG module primitives and chain-complex export
    -- Installing differentials, reading degree data,
    and exporting to Complex
  * maxDegree -- Computes the maximum homological degree of a
    DGAlgebra
  * maxDegree(DGModule) -- Largest hom-degree
    present in a DG module
  * toComplex(DGQuotientModule), --
    Export a DG quotient module to a Complex

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

  * maxDegree(DGQuotientModule), --
    Largest hom-degree present in a DG quotient module
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7687:0.

getBasis(ZZ,DGModule) -- Basis of the hom-degree-n piece of a DG module
***********************************************************************

  * Function: getBasis,
  * Usage:
        b = getBasis(n, M)
  * Inputs:
      * n, an integer (Macaulay2Doc), A homological degree.
      * M, an instance of the type DGModule,
  * Optional inputs (Macaulay2Doc),:
      * Limit, => ...,
        default value -1, Maximum number of basis elements to return from
        getBasis
  * Outputs:
      * b, a matrix (Macaulay2Doc), A one-row matrix over
        M.natural whose entries are the basis elements of F_n(M), the
        hom-degree-n piece of M.natural over A.ring.

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

getBasis(n, M) delegates to basis (Macaulay2Doc), on the underlying
A.natural-module M.natural, restricting to the variables of A.natural.  The
result is the piece of M on which moduleDifferential(n, M) acts as its
source-side basis.

+-------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)              |
|                                                 |
|o1 = R                                           |
|                                                 |
|o1 : QuotientRing                                |
+-------------------------------------------------+
|i2 : KM = koszulComplexDGM R^1                   |
|                                                 |
|o2 = {Base ring => R                    }        |
|      DG algebra => R[T   ..T   ]                |
|                       1,1   1,2                 |
|                                       1         |
|      Natural module => (R[T   ..T   ])          |
|                            1,1   1,2            |
|      Generator degrees => {{0, 0}}              |
|      Differentials on gens => {0}               |
|                                                 |
|o2 : DGModule                                    |
+-------------------------------------------------+
|i3 : b = getBasis(1, KM)                         |
|                                                 |
|o3 = | T_(1,1) T_(1,2) |                         |
|                                                 |
|                           1                    2|
|o3 : Matrix (R[T   ..T   ])  <-- (R[T   ..T   ]) |
|                1,1   1,2            1,1   1,2   |
+-------------------------------------------------+
|i4 : assert(instance(b, Matrix))                 |
+-------------------------------------------------+
|i5 : assert(numcols b == 2)                      |
+-------------------------------------------------+

See also
========

  * DG module primitives and chain-complex export
    -- Installing differentials, reading degree data,
    and exporting to Complex
  * getBasis -- Get a basis for a particular homological
    degree of a DG algebra.
  * getBasis(ZZ,DGAlgebra) -- Get a basis for a particular
    homological degree of a DG algebra.
  * moduleDifferential -- The hom-degree-n
    differential of a DG module as a matrix over the base ring

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

  * getBasis(ZZ,DGModule) -- Basis of the
    hom-degree-n piece of a DG module
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7724:0.

toComplex(DGModule) -- Export a DG module to a Complex of free base-ring modules
********************************************************************************

  * Function: toComplex,
  * Usage:
        C = toComplex M
  * Inputs:
      * M, an instance of the type DGModule,
  * Outputs:
      * C, a complex (Complexes), A Complex (Complexes),
        of free A.ring-modules whose i-th differential is
        moduleDifferential(i+1, M).

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

toComplex packages the per-degree module differentials as an ordinary
Complex (Complexes), so that the result can flow through the rest of
the Complexes, package.  The one-argument form uses
maxDegree M as the truncation bound and errors out if that is infinity; use
toComplex(DGModule,ZZ), to supply an
explicit bound. The result is not cached by this method (use dgComplex,
for a cached variant).

+------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)             |
|                                                |
|o1 = R                                          |
|                                                |
|o1 : QuotientRing                               |
+------------------------------------------------+
|i2 : KM = koszulComplexDGM R^1                  |
|                                                |
|o2 = {Base ring => R                    }       |
|      DG algebra => R[T   ..T   ]               |
|                       1,1   1,2                |
|                                       1        |
|      Natural module => (R[T   ..T   ])         |
|                            1,1   1,2           |
|      Generator degrees => {{0, 0}}             |
|      Differentials on gens => {0}              |
|                                                |
|o2 : DGModule                                   |
+------------------------------------------------+
|i3 : C = toComplex KM                           |
|                                                |
|      1      2      1                           |
|o3 = R  <-- R  <-- R                            |
|                                                |
|     0      1      2                            |
|                                                |
|o3 : Complex                                    |
+------------------------------------------------+
|i4 : assert(instance(C, Complex))               |
+------------------------------------------------+
|i5 : assert(C.dd_1 == moduleDifferential(1, KM))|
+------------------------------------------------+
|i6 : assert(C.dd_2 == moduleDifferential(2, KM))|
+------------------------------------------------+

See also
========

  * DG module primitives and chain-complex export
    -- Installing differentials, reading degree data,
    and exporting to Complex
  * toComplex -- Converts a DGAlgebra to a Complex
  * toComplex(DGModule,ZZ) -- Export a DG
    module to a Complex with an explicit hom-degree bound
  * toComplex(DGAlgebra) -- Converts a DGAlgebra to a Complex
  * dgComplex -- Package a DG algebra or DG module as a
    Complex of free base-ring modules
  * moduleDifferential -- The hom-degree-n
    differential of a DG module as a matrix over the base ring

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

  * toComplex(DGModule) -- Export a DG module
    to a Complex of free base-ring modules
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7764:0.

toComplex(DGModule,ZZ) -- Export a DG module to a Complex with an explicit hom-degree bound
*******************************************************************************************

  * Function: toComplex,
  * Usage:
        C = toComplex(M, n)
  * Inputs:
      * M, an instance of the type DGModule,
      * n, an integer (Macaulay2Doc), A hom-degree upper bound.
  * Outputs:
      * C, a complex (Complexes), A Complex (Complexes),
        of free A.ring-modules, truncated at hom-degree n.

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

The explicit-bound form of toComplex(DGModule).
Supplying a bound is required when the ambient DG algebra has infinite
hom-degree (as for an acyclicClosure), and convenient
when a low bound suffices.

+-----------------------------------------+
|i1 : R = QQ[x, y, z]                     |
|                                         |
|o1 = R                                   |
|                                         |
|o1 : PolynomialRing                      |
+-----------------------------------------+
|i2 : KM = koszulComplexDGM R^1           |
|                                         |
|o2 = {Base ring => R                    }|
|      DG algebra => R[T   ..T   ]        |
|                       1,1   1,3         |
|                                       1 |
|      Natural module => (R[T   ..T   ])  |
|                            1,1   1,3    |
|      Generator degrees => {{0, 0}}      |
|      Differentials on gens => {0}       |
|                                         |
|o2 : DGModule                            |
+-----------------------------------------+
|i3 : C = toComplex(KM, 2)                |
|                                         |
|      1      3      3                    |
|o3 = R  <-- R  <-- R                     |
|                                         |
|     0      1      2                     |
|                                         |
|o3 : Complex                             |
+-----------------------------------------+
|i4 : assert(instance(C, Complex))        |
+-----------------------------------------+
|i5 : assert(max C == 2)                  |
+-----------------------------------------+

See also
========

  * DG module primitives and chain-complex export
    -- Installing differentials, reading degree data,
    and exporting to Complex
  * toComplex -- Converts a DGAlgebra to a Complex
  * toComplex(DGModule) -- Export a DG module
    to a Complex of free base-ring modules
  * dgComplex -- Package a DG algebra or DG module as a
    Complex of free base-ring modules
  * moduleDifferential -- The hom-degree-n
    differential of a DG module as a matrix over the base ring

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

  * toComplex(DGModule,ZZ) -- Export a DG
    module to a Complex with an explicit hom-degree bound
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7799:0.

toComplex(DGQuotientModule) -- Export a DG quotient module to a Complex
***********************************************************************

  * Function: toComplex,
  * Usage:
        C = toComplex Q
  * Inputs:
      * Q, an instance of the type DGQuotientModule,
  * Outputs:
      * C, a complex (Complexes), The cokernel of the chain map
        induced by the inclusion Q.subDGModule.inclusion; equivalently, the
        per-degree quotient complex of the ambient.

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

For a DG quotient module Q = M / S, toComplex Q builds the cokernel at the
Complex (Complexes), level: it exports the ambient DG module M
via toComplex(DGModule), exports the inclusion
of S via toComplexMap(DGModuleMap), and
takes the cokernel of the resulting ComplexMap (Complexes).
If Q was previously passed through prune(DGQuotientModule),
the cached pruned complex is returned instead.

+------------------------------------+
|i1 : R = ZZ/101[x]                  |
|                                    |
|o1 = R                              |
|                                    |
|o1 : PolynomialRing                 |
+------------------------------------+
|i2 : A = koszulComplexDGA R         |
|                                    |
|o2 = {Ring => R                    }|
|      Underlying algebra => R[T   ] |
|                               1,1  |
|      Differential => {x}           |
|                                    |
|o2 : DGAlgebra                      |
+------------------------------------+
|i3 : M = freeDGModule(A, {0})       |
|                                    |
|o3 = {Base ring => R               }|
|      DG algebra => R[T   ]         |
|                       1,1          |
|                                 1  |
|      Natural module => (R[T   ])   |
|                            1,1     |
|      Generator degrees => {{0, 0}} |
|      Differentials on gens => {0}  |
|                                    |
|o3 : DGModule                       |
+------------------------------------+
|i4 : z = zeroDGModuleMap(M, M)      |
|                                    |
|                         1          |
|o4 = {Source => (R[T   ]) }         |
|                    1,1             |
|                         1          |
|      Target => (R[T   ])           |
|                    1,1             |
|      Natural => 0                  |
|                                    |
|o4 : DGModuleMap                    |
+------------------------------------+
|i5 : Q = cokernel z                 |
|                                    |
|o5 = DGQuotientModule Q = M / S     |
|                          1         |
|     Q.natural = (R[T   ])          |
|                     1,1            |
|     Degrees   = {{0, 0}}           |
|                                    |
|o5 : DGQuotientModule               |
+------------------------------------+
|i6 : CM = toComplex M               |
|                                    |
|      1      1                      |
|o6 = R  <-- R                       |
|                                    |
|     0      1                       |
|                                    |
|o6 : Complex                        |
+------------------------------------+
|i7 : CQ = toComplex Q               |
|                                    |
|      1      1                      |
|o7 = R  <-- R                       |
|                                    |
|     0      1                       |
|                                    |
|o7 : Complex                        |
+------------------------------------+
|i8 : assert(rank CM_0 == rank CQ_0) |
+------------------------------------+
|i9 : assert(rank CM_1 == rank CQ_1) |
+------------------------------------+

See also
========

  * DG module primitives and chain-complex export
    -- Installing differentials, reading degree data,
    and exporting to Complex
  * toComplex(DGModule) -- Export a DG module
    to a Complex of free base-ring modules
  * toComplexMap(DGModuleMap) -- Export a
    DG module map to a ComplexMap
  * prune(DGQuotientModule) -- Minimize the
    presentation of a DG quotient module

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

  * toComplex(DGQuotientModule), --
    Export a DG quotient module to a Complex
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7841:0.

toComplex(DGIdeal) -- Export a DG ideal to a Complex (not yet implemented)
**************************************************************************

  * Function: toComplex,
  * Usage:
        C = toComplex I
  * Inputs:
      * I, an instance of the type DGIdeal,
  * Outputs:
      * C, a complex (Complexes),

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

toComplex on a DGIdeal, is not yet implemented.  The natural
definition views I as a DG submodule of the regular DG module A.natural over A,
but a canonical wrapper for the regular-representation view of A as a DG module
over itself is not yet in the package, so the method raises an informative
error pointing at the currently available alternatives.

Use toComplex(ambient I / I) to obtain the Complex (Complexes),
of the quotient DG algebra, or read the underlying data via ideal I and gens I.

+-------------------------------------------------+
|i1 : R = ZZ/101[x]                               |
|                                                 |
|o1 = R                                           |
|                                                 |
|o1 : PolynomialRing                              |
+-------------------------------------------------+
|i2 : A = koszulComplexDGA R                      |
|                                                 |
|o2 = {Ring => R                    }             |
|      Underlying algebra => R[T   ]              |
|                               1,1               |
|      Differential => {x}                        |
|                                                 |
|o2 : DGAlgebra                                   |
+-------------------------------------------------+
|i3 : T = (gens A.natural)#0                      |
|                                                 |
|o3 = T                                           |
|      1,1                                        |
|                                                 |
|o3 : R[T   ]                                     |
|        1,1                                      |
+-------------------------------------------------+
|i4 : I = dgIdeal(A, {T})                         |
|                                                 |
|o4 = DGIdeal of R[T   ]                          |
|                   1,1                           |
|     generators => | x T_(1,1) |                 |
|                                                 |
|o4 : DGIdeal                                     |
+-------------------------------------------------+
|i5 : errored = try (toComplex I; false) else true|
|                                                 |
|o5 = true                                        |
+-------------------------------------------------+
|i6 : assert(errored)                             |
+-------------------------------------------------+

See also
========

  * DG module primitives and chain-complex export
    -- Installing differentials, reading degree data,
    and exporting to Complex
  * Operations on DG Ideals -- Sum, product,
    power, intersection, colon, and other ideal-algebra operations on DG ideals
  * DGIdeal -- The class of d-closed graded ideals of a DG
    algebra
  * dgIdeal -- Construct a DG ideal from a list, matrix, or
    ideal of generators
  * DGAlgebra / DGIdeal -- Quotient DG algebra by a
    DG ideal

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

  * toComplex(DGIdeal) -- Export a DG ideal to a
    Complex (not yet implemented)
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7881:0.

toComplexMap(DGModuleMap) -- Export a DG module map to a ComplexMap
*******************************************************************

  * Function: toComplexMap,
  * Usage:
        cm = toComplexMap f
  * Inputs:
      * f, an instance of the type DGModuleMap, A DG module
        map M --> N.
  * Optional inputs (Macaulay2Doc),:
      * AssertWellDefined, => ..., default value true,
        Construct the ComplexMap associated to a DGAlgebraMap
      * EndDegree, => ..., default value -1, Construct the
        ComplexMap associated to a DGAlgebraMap
  * Outputs:
      * cm, a map of complexes (Complexes), The induced
        ComplexMap (Complexes), toComplex M --> toComplex N.

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

toComplexMap f assembles the per-degree pieces of f into a ComplexMap (Complexes).
When either side has infinite hom-degree, an
EndDegree, bound must be supplied; the option
AssertWellDefined, (default true) causes isWellDefined f to
be checked up front.  When the target is a DG quotient module only the
canonical projection is supported; the result is the induced quotient chain
map.  Use toComplexMap(DGModuleMap,ZZ),
to extract a single per-degree component
instead.

+-----------------------------------------------------------+
|i1 : R = QQ[a, b] / ideal(a^2, b^2)                        |
|                                                           |
|o1 = R                                                     |
|                                                           |
|o1 : QuotientRing                                          |
+-----------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                |
|                                                           |
|o2 = {Ring => R                          }                 |
|      Underlying algebra => R[T   ..T   ]                  |
|                               1,1   1,2                   |
|      Differential => {a, b}                               |
|                                                           |
|o2 : DGAlgebra                                             |
+-----------------------------------------------------------+
|i3 : phi = dgAlgebraMap(A, A, matrix {gens A.natural})     |
|                                                           |
|o3 = map (R[T   ..T   ], R[T   ..T   ], {T   , T   , a, b})|
|             1,1   1,2      1,1   1,2     1,1   1,2        |
|                                                           |
|o3 : DGAlgebraMap                                          |
+-----------------------------------------------------------+
|i4 : cm = toComplexMap phi                                 |
|                                                           |
|          1             1                                  |
|o4 = 0 : R  <--------- R  : 0                              |
|               | 1 |                                       |
|                                                           |
|          2                   2                            |
|     1 : R  <--------------- R  : 1                        |
|               {1} | 1 0 |                                 |
|               {1} | 0 1 |                                 |
|                                                           |
|          1                 1                              |
|     2 : R  <------------- R  : 2                          |
|               {2} | 1 |                                   |
|                                                           |
|o4 : ComplexMap                                            |
+-----------------------------------------------------------+
|i5 : assert(instance(cm, ComplexMap))                      |
+-----------------------------------------------------------+

See also
========

  * DG module primitives and chain-complex export
    -- Installing differentials, reading degree data,
    and exporting to Complex
  * toComplexMap -- Construct the ComplexMap associated to
    a DGAlgebraMap
  * toComplexMap(DGModuleMap,ZZ), --
    The per-hom-degree component of a DG module map as a matrix
  * toComplexMap(DGAlgebraMap) -- Construct the ComplexMap
    associated to a DGAlgebraMap
  * toComplex(DGModule) -- Export a DG module
    to a Complex of free base-ring modules
  * identityDGModuleMap -- The identity DGModuleMap
    on a DG module

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

  * toComplexMap(DGModuleMap) -- Export a
    DG module map to a ComplexMap
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7922:0.

toComplexMap(DGModuleMap,ZZ) -- The per-hom-degree component of a DG module map as a matrix
*******************************************************************************************

  * Function: toComplexMap,
  * Usage:
        m = toComplexMap(f, n)
  * Inputs:
      * f, an instance of the type DGModuleMap, A DG module
        map M --> N.
      * n, an integer (Macaulay2Doc), A homological degree.
  * Optional inputs (Macaulay2Doc),:
      * AssertWellDefined, => ..., default value true,
        Construct the ComplexMap associated to a DGAlgebraMap
      * EndDegree, => ..., default value -1, Construct the
        ComplexMap associated to a DGAlgebraMap
  * Outputs:
      * m, a matrix (Macaulay2Doc), The hom-degree-n component
        F_n(M) --> F_n(N) as an A.ring-linear matrix.

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

Builds the A.ring-linear matrix that f induces on the hom-degree-n pieces of
M.natural and N.natural.  This is the per-degree primitive used by
toComplexMap(DGModuleMap), when assembling a
full ComplexMap (Complexes).

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)                                          |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : Mdg = minimalSemifreeResolution(koszulComplexDGA R, R^1 / ideal(x, y),  |
|                                                                             |
|o2 = {Base ring => R                                                         |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       6                                     |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}, {4, 4}, {4, 4}, {4, 4}}  |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |, |     0    |, |
|                                   |     0    |  |     0    |  | xT_(1,1) |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                                                             |
|o2 : DGModule                                                                |
|-----------------------------------------------------------------------------|
|EndDegree => 3)                                                              |
|                                                                             |
|                            }                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
| |     0    |, |     0    |}                                                 |
| | yT_(1,2) |  |     0    |                                                  |
| | xT_(1,1) |  | yT_(1,2) |                                                  |
| |     0    |  |     0    |                                                  |
| |     0    |  |     0    |                                                  |
| |     0    |  |     0    |                                                  |
+-----------------------------------------------------------------------------+
|i3 : idM = identityDGModuleMap Mdg                                           |
|                                                                             |
|                               6                                             |
|o3 = {Source => (R[T   ..T   ])        }                                     |
|                    1,1   1,2                                                |
|                               6                                             |
|      Target => (R[T   ..T   ])                                              |
|                    1,1   1,2                                                |
|      Natural => {0, 0} | 1 0 0 0 0 0 |                                      |
|                 {2, 2} | 0 1 0 0 0 0 |                                      |
|                 {2, 2} | 0 0 1 0 0 0 |                                      |
|                 {4, 4} | 0 0 0 1 0 0 |                                      |
|                 {4, 4} | 0 0 0 0 1 0 |                                      |
|                 {4, 4} | 0 0 0 0 0 1 |                                      |
|                                                                             |
|o3 : DGModuleMap                                                             |
+-----------------------------------------------------------------------------+
|i4 : all(0..3, n -> (                                                        |
|         cm := toComplexMap(idM, n);                                         |
|         source cm == target cm and cm == id_(source cm)                     |
|         ))                                                                  |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * DG module primitives and chain-complex export
    -- Installing differentials, reading degree data,
    and exporting to Complex
  * toComplexMap -- Construct the ComplexMap associated to
    a DGAlgebraMap
  * toComplexMap(DGModuleMap) -- Export a
    DG module map to a ComplexMap
  * toComplex(DGModule) -- Export a DG module
    to a Complex of free base-ring modules
  * identityDGModuleMap -- The identity DGModuleMap
    on a DG module

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

  * toComplexMap(DGModuleMap,ZZ), --
    The per-hom-degree component of a DG module map as a matrix
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:7963:0.

displayBlockDiff -- Shows natural decomposition of a map in the Tate resolution
*******************************************************************************

  * Usage:
        displayBlockDiff (A, n)
        displayBlockDiff (A, LA, LA)
        displayBlockDiff (A, L, L)
        displayBlockDiff (A, V)
  * Inputs:
      * A, an instance of the type DGAlgebra, of the sort
        produced by acyclicClosure, or killCycles,
      * n, an integer (Macaulay2Doc),
      * LA, an array (Macaulay2Doc), of the form [L] where L is a
        list representing a multi-index in the complex
      * L, a list (Macaulay2Doc), of indices as above
      * V, a visible list (Macaulay2Doc), a list, array or
        sequence representing a (single) multi-index in the complex defined by
        A

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

For example, consider the first five steps in the resolution of the residue
field in the following example:

+--------------------------------------------------------------+
|i1 : R = QQ[x,y,z]/(ideal(x^3,y^3,z^3,x*y*z))                 |
|                                                              |
|o1 = R                                                        |
|                                                              |
|o1 : QuotientRing                                             |
+--------------------------------------------------------------+
|i2 : G = betti freeResolution (coker vars R, LengthLimit => 5)|
|                                                              |
|            0 1 2  3  4  5                                    |
|o2 = total: 1 3 7 16 37 86                                    |
|         0: 1 3 3  1  .  .                                    |
|         1: . . 4 12 12  4                                    |
|         2: . . .  3 22 48                                    |
|         3: . . .  .  3 33                                    |
|         4: . . .  .  .  1                                    |
|                                                              |
|o2 : BettiTally                                               |
+--------------------------------------------------------------+

It is a free graded-commutative divided power algebra on generator of each
degree starting with 1. We can compute the beginning of the complex
corresponding to the first 3 factors with as

+-----------------------------------------------------------------------------+
|i3 : A = acyclicClosure(R,EndDegree => 2)                                    |
|                                                                             |
|o3 = {Ring => R                                                              |
|      Underlying algebra => R[T   ..T   , T   ..T   , T   ..T   ]            |
|                               1,1   1,3   2,1   2,4   3,1   3,3             |
|                                           2       2       2       2         |
|      Differential => {x, y, z, y*z*T   , x T   , y T   , z T   , z T   ,    |
|                                     1,1     1,1     1,2     1,3     2,1     |
|                                                                             |
|o3 : DGAlgebra                                                               |
|-----------------------------------------------------------------------------|
|                   }                                                         |
|                                                                             |
|                                                                             |
|                                                                             |
|y*z*T   , x*z*T   }                                                          |
|     2,2       2,3                                                           |
+-----------------------------------------------------------------------------+
|i4 : F = toComplex(A, 5);                                                    |
+-----------------------------------------------------------------------------+
|i5 : betti F                                                                 |
|                                                                             |
|            0 1 2  3  4  5                                                   |
|o5 = total: 1 3 7 16 31 55                                                   |
|         0: 1 3 3  1  .  .                                                   |
|         1: . . 4 12 12  4                                                   |
|         2: . . .  3 19 39                                                   |
|         3: . . .  .  . 12                                                   |
|                                                                             |
|o5 : BettiTally                                                              |
+-----------------------------------------------------------------------------+
|i6 : betti F                                                                 |
|                                                                             |
|            0 1 2  3  4  5                                                   |
|o6 = total: 1 3 7 16 31 55                                                   |
|         0: 1 3 3  1  .  .                                                   |
|         1: . . 4 12 12  4                                                   |
|         2: . . .  3 19 39                                                   |
|         3: . . .  .  . 12                                                   |
|                                                                             |
|o6 : BettiTally                                                              |
+-----------------------------------------------------------------------------+

Since we gave acyclicClosure, the EndDegree 2, the
complex produced is exact up to step 2; that is betti F and betti G agree up to
the column 3. There are 3 chunks of generators in A, of homological degrees
1,2,3.

From the betti table of F we see the three generators of the exterior algebra K
as the linear part of the resolution. The second strand, 4,12,12,4 is the
tensor product of K with the 4 generators of A that have homological degree 2
and correspond to the 4 generators of I; thus they have internal degree 3. We
also see that A has three generators in homological degree 3 and internal
degree 5. K multiplied by these generators accounts for 3,9,9 of the 3rd
strand, while the symmetric square of the 4 generators of homological degree 2,
account for 0,10,0 and the product of these with the generators of degree 1
account for the remaining 0,0,30. Finally the 12 in the 4th row represents the
product of the 4 generators of A in homological degree with the 3 in degree 3.

The native display of the differentials of this complex does not distinguish
these pieces, but displayBlockDiff allows one to look at them in various ways:

+-----------------------------------------------------------------------------+
|i7 : F.dd_3                                                                  |
|                                                                             |
|o7 = {2} | z  0 yz 0  0 x2 0  -y2 0 0  0   0   0 0  0  0  |                  |
|     {2} | -y 0 0  yz 0 0  x2 0   0 0  -z2 0   0 0  0  0  |                  |
|     {2} | x  0 0  0  0 0  0  0   0 y2 0   -z2 0 0  0  0  |                  |
|     {3} | 0  x y  z  0 0  0  0   0 0  0   0   0 z2 0  0  |                  |
|     {3} | 0  0 0  0  x y  z  0   0 0  0   0   0 0  yz 0  |                  |
|     {3} | 0  0 0  0  0 0  0  x   y z  0   0   0 0  0  xz |                  |
|     {3} | 0  0 0  0  0 0  0  0   0 0  x   y   z 0  0  0  |                  |
|                                                                             |
|             7      16                                                       |
|o7 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i8 : displayBlockDiff(A,3)                                                   |
|                                                                             |
|     +---------+----------------+------------------------------------------+-|
|o8 = |    .    |    {0, 0, 3}   |                 {1, 2, 0}                | |
|     +---------+----------------+------------------------------------------+-|
|     |{0, 2, 0}|{3} | z2 0  0  ||      {3} | x 0 0 0 y 0 0 0 z 0 0 0 |     | |
|     |         |{3} | 0  yz 0  ||      {3} | 0 x 0 0 0 y 0 0 0 z 0 0 |     | |
|     |         |{3} | 0  0  xz ||      {3} | 0 0 x 0 0 0 y 0 0 0 z 0 |     | |
|     |         |{3} | 0  0  0  ||      {3} | 0 0 0 x 0 0 0 y 0 0 0 z |     | |
|     +---------+----------------+------------------------------------------+-|
|     |{2, 0, 0}|        0       |{2} | 0 0 -y2 0   yz x2 0 0   0  0  0  0 ||{|
|     |         |                |{2} | 0 0 0   -z2 0  0  0 0   yz x2 0  0 ||{|
|     |         |                |{2} | 0 0 0   0   0  0  0 -z2 0  0  y2 0 ||{|
|     +---------+----------------+------------------------------------------+-|
|-----------------------------------------------------------------------------|
|---------+                                                                   |
|{3, 0, 0}|                                                                   |
|---------+                                                                   |
|    0    |                                                                   |
|         |                                                                   |
|         |                                                                   |
|         |                                                                   |
|---------+                                                                   |
|2} | z  ||                                                                   |
|2} | -y ||                                                                   |
|2} | x  ||                                                                   |
|---------+                                                                   |
+-----------------------------------------------------------------------------+

Here the triples of numbers represent the number of factors from the generators
of each of the three chunks of variables: the first index gives the number from
the Koszul complex, the second from the 4 variable in homological degree 2 and
the third the number from the 3 variables of homological degree 3. Thus the sum
of the three indices is the homological degree. The sources of the blocks are
listed on the top row, the targets are given by the columns. We can see the
lists of indices of the source and target with Example indices source
blockDiff(A,5) indices target blockDiff(A,5)

We can extract one or several blocks from F.dd_3 as follows:

+-----------------------------------------------------------------------------+
|i9 : R = QQ[x,y,z]/(ideal(x^3,y^3,z^3,x*y*z))                                |
|                                                                             |
|o9 = R                                                                       |
|                                                                             |
|o9 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i10 : A = acyclicClosure(R,EndDegree => 2)                                   |
|                                                                             |
|o10 = {Ring => R                                                             |
|       Underlying algebra => R[T   ..T   , T   ..T   , T   ..T   ]           |
|                                1,1   1,3   2,1   2,4   3,1   3,3            |
|                                            2       2       2       2        |
|       Differential => {x, y, z, y*z*T   , x T   , y T   , z T   , z T   ,   |
|                                      1,1     1,1     1,2     1,3     2,1    |
|                                                                             |
|o10 : DGAlgebra                                                              |
|-----------------------------------------------------------------------------|
|                   }                                                         |
|                                                                             |
|                                                                             |
|                                                                             |
|y*z*T   , x*z*T   }                                                          |
|     2,2       2,3                                                           |
+-----------------------------------------------------------------------------+

We can specify a lists of source and target degrees, either as lists
representing an index for th source and an index for the target:

+-------------------------------------------------+
|i11 : displayBlockDiff(A,  {0,2,3}, {0,4,0})     |
|                                                 |
|o11 = {6} | z2 0  0  0  0  0  0  0  0  0  0  0  ||
|      {6} | 0  yz 0  z2 0  0  0  0  0  0  0  0  ||
|      {6} | 0  0  xz 0  0  0  z2 0  0  0  0  0  ||
|      {6} | 0  0  0  0  0  0  0  0  0  z2 0  0  ||
|      {6} | 0  0  0  0  yz 0  0  0  0  0  0  0  ||
|      {6} | 0  0  0  0  0  xz 0  yz 0  0  0  0  ||
|      {6} | 0  0  0  0  0  0  0  0  0  0  yz 0  ||
|      {6} | 0  0  0  0  0  0  0  0  xz 0  0  0  ||
|      {6} | 0  0  0  0  0  0  0  0  0  0  0  xz ||
|      {6} | 0  0  0  0  0  0  0  0  0  0  0  0  ||
|                                                 |
|              10      12                         |
|o11 : Matrix R   <-- R                           |
+-------------------------------------------------+

or as a pair of arrays of such lists

+--------------------------------------------------------+
|i12 : displayBlockDiff(A,  [{0,2,3}], [{1,0,3},{0,4,0}])|
|                                                        |
|o12 = {6} | yz 0  0  x2 0  0  0  0  0  0  0  0  |       |
|      {6} | 0  yz 0  0  x2 0  0  0  0  0  0  0  |       |
|      {6} | 0  0  yz 0  0  x2 0  0  0  0  0  0  |       |
|      {6} | 0  0  0  0  0  0  y2 0  0  0  0  0  |       |
|      {6} | 0  0  0  0  0  0  0  y2 0  0  0  0  |       |
|      {6} | 0  0  0  0  0  0  0  0  y2 0  0  0  |       |
|      {6} | 0  0  0  0  0  0  0  0  0  z2 0  0  |       |
|      {6} | 0  0  0  0  0  0  0  0  0  0  z2 0  |       |
|      {6} | 0  0  0  0  0  0  0  0  0  0  0  z2 |       |
|      {6} | z2 0  0  0  0  0  0  0  0  0  0  0  |       |
|      {6} | 0  yz 0  z2 0  0  0  0  0  0  0  0  |       |
|      {6} | 0  0  xz 0  0  0  z2 0  0  0  0  0  |       |
|      {6} | 0  0  0  0  0  0  0  0  0  z2 0  0  |       |
|      {6} | 0  0  0  0  yz 0  0  0  0  0  0  0  |       |
|      {6} | 0  0  0  0  0  xz 0  yz 0  0  0  0  |       |
|      {6} | 0  0  0  0  0  0  0  0  0  0  yz 0  |       |
|      {6} | 0  0  0  0  0  0  0  0  xz 0  0  0  |       |
|      {6} | 0  0  0  0  0  0  0  0  0  0  0  xz |       |
|      {6} | 0  0  0  0  0  0  0  0  0  0  0  0  |       |
|                                                        |
|              19      12                                |
|o12 : Matrix R   <-- R                                  |
+--------------------------------------------------------+

or look at all the blocks with a given target summand with:

+-----------------------------------------------------------------------------+
|i13 : displayBlockDiff(A,  (1,0,3) )                                         |
|                                                                             |
|o13 = {6} | yz 0  0  x2 0  0  0  0  0  0  0  0  0 0 0 0 0 0 0 0 0 0 0 0 0 0 0|
|      {6} | 0  yz 0  0  x2 0  0  0  0  0  0  0  0 0 0 0 0 0 0 0 0 0 0 0 0 0 0|
|      {6} | 0  0  yz 0  0  x2 0  0  0  0  0  0  0 0 0 0 0 0 0 0 0 0 0 0 0 0 0|
|      {6} | 0  0  0  0  0  0  y2 0  0  0  0  0  0 0 0 0 0 0 0 0 0 0 0 0 0 0 0|
|      {6} | 0  0  0  0  0  0  0  y2 0  0  0  0  0 0 0 0 0 0 0 0 0 0 0 0 0 0 0|
|      {6} | 0  0  0  0  0  0  0  0  y2 0  0  0  0 0 0 0 0 0 0 0 0 0 0 0 0 0 0|
|      {6} | 0  0  0  0  0  0  0  0  0  z2 0  0  0 0 0 0 0 0 0 0 0 0 0 0 0 0 0|
|      {6} | 0  0  0  0  0  0  0  0  0  0  z2 0  0 0 0 0 0 0 0 0 0 0 0 0 0 0 0|
|      {6} | 0  0  0  0  0  0  0  0  0  0  0  z2 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 -y 0  0  -z 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  -y 0  0  -z 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  -y 0  0  -z 0  0  0  0 0 0 0 |     |
|      0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 x  0  0  0  0  0  -z 0  0  0 0 0 0 |     |
|      0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0  x  0  0  0  0  0  -z 0  0 0 0 0 |     |
|      0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0  0  x  0  0  0  0  0  -z 0 0 0 0 |     |
|      0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0  0  0  x  0  0  y  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  x  0  0  y  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  x  0  0  y  0 0 0 0 |     |
|                                                                             |
|              9      55                                                      |
|o13 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+

See also
========

  * blockDiff -- prepares a map for display
  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension

Ways to use displayBlockDiff:
=============================

  * "displayBlockDiff(DGAlgebra,Array,Array)"
  * "displayBlockDiff(DGAlgebra,List,List)"
  * "displayBlockDiff(DGAlgebra,VisibleList)"
  * "displayBlockDiff(DGAlgebra,ZZ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9972:0.

acyclicClosure -- Tate's construction of a semifree acyclic DG algebra extension
********************************************************************************

  * Usage:
        B = acyclicClosure A
        B = acyclicClosure(A, EndDegree => n)
  * Inputs:
      * A, an instance of the type DGAlgebra, The starting DG
        algebra.
  * Optional inputs (Macaulay2Doc),:
      * StartDegree,
        => an integer (Macaulay2Doc), default value 1, First
        hom-degree at which to begin killing homology.  Defaults to 1.
      * EndDegree,
        => an integer (Macaulay2Doc), default value 3, Last
        hom-degree at which homology is killed.  Defaults to 3.
      * Variable, =>
        a string (Macaulay2Doc), default value null, Base name
        used for any new adjoined generators (Strings and Symbols are both
        accepted).  Defaults to reusing the base symbol already in use by A, or
        "T" if A has no generators.
  * Outputs:
      * B, an instance of the type DGAlgebra, A semifree
        extension of A with the same ring and the same degree-zero homology,
        whose positive-degree homology has been killed in every hom-degree from
        StartDegree through EndDegree.

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

Tate's construction.  Starting from A, acyclicClosure iterates
killCycles, from StartDegree up through EndDegree.  At each step n,
a minimal set of cycle representatives of H_n(A) is computed and a new DG
algebra generator is adjoined for each, placed in hom-degree n + 1 and whose
differential is the chosen cycle.  Adjoining follows the graded-commutative
convention: generators of odd hom-degree are exterior (skew-commutative,
square-zero) while generators of even hom-degree are polynomial, so the result
is a free DG algebra in the sense of Tate/Gulliksen.  If A is the Koszul
complex on a regular sequence, no homology exists to kill and acyclicClosure
returns A unchanged; otherwise new generators appear, recording the deviations
of A.

Variable-naming convention.  Both the existing generators of A and the newly
adjoined generators use a doubly-indexed naming scheme base_(i, j), where i is
the homological degree (the first entry of the multi-degree) and j is a
1-indexed counter among generators at that hom-degree.  Counters continue past
those already present in A.  For example, if A already has three generators
T_(1,1), T_(1,2), T_(1,3) in hom-degree 1 and two new hom-degree-2 cycles need
killing, the output has new generators T_(2,1) and T_(2,2).  The Variable
option only affects the base symbol for new generators; existing names are
preserved.

Over a complete intersection R = k[a, b, c]/(a^3, b^3, c^3), the Koszul complex
has three nonzero hom-degree-2 cycles (one per relation) which must be killed,
introducing three new polynomial generators T_(2,1), T_(2,2), T_(2,3):

+--------------------------------------------------------+
|i1 : R = ZZ/101[a, b, c] / ideal(a^3, b^3, c^3)         |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : QuotientRing                                       |
+--------------------------------------------------------+
|i2 : A = koszulComplexDGA R                             |
|                                                        |
|o2 = {Ring => R                          }              |
|      Underlying algebra => R[T   ..T   ]               |
|                               1,1   1,3                |
|      Differential => {a, b, c}                         |
|                                                        |
|o2 : DGAlgebra                                          |
+--------------------------------------------------------+
|i3 : gens A.natural                                     |
|                                                        |
|o3 = {T   , T   , T   }                                 |
|       1,1   1,2   1,3                                  |
|                                                        |
|o3 : List                                               |
+--------------------------------------------------------+
|i4 : B = acyclicClosure(A, EndDegree => 2)              |
|                                                        |
|o4 = {Ring => R                                        }|
|      Underlying algebra => R[T   ..T   ]               |
|                               1,1   2,3                |
|                                 2       2       2      |
|      Differential => {a, b, c, a T   , b T   , c T   } |
|                                   1,1     1,2     1,3  |
|                                                        |
|o4 : DGAlgebra                                          |
+--------------------------------------------------------+
|i5 : gens B.natural                                     |
|                                                        |
|o5 = {T   , T   , T   , T   , T   , T   }               |
|       1,1   1,2   1,3   2,1   2,2   2,3                |
|                                                        |
|o5 : List                                               |
+--------------------------------------------------------+
|i6 : take(flatten entries matrix B.diff, 6)             |
|                                                        |
|                2       2       2                       |
|o6 = {a, b, c, a T   , b T   , c T   }                  |
|                  1,1     1,2     1,3                   |
|                                                        |
|o6 : List                                               |
+--------------------------------------------------------+

Here the new generators satisfy d(T_(2,i)) = a_i^2 T_(1,i), the cycle
representatives of H_2 for each element of the regular sequence.  The result is
quasi-isomorphic to R/(a,b,c) in hom-degrees <= 2.

For larger EndDegree, the construction keeps going; over a c.i. no further
generators appear because the Koszul-plus-polynomial DG algebra is already a
resolution of the residue field (this is Tate's theorem):

+--------------------------------------------------------+
|i7 : B2 = acyclicClosure(A, EndDegree => 4)             |
|                                                        |
|o7 = {Ring => R                                        }|
|      Underlying algebra => R[T   ..T   ]               |
|                               1,1   2,3                |
|                                 2       2       2      |
|      Differential => {a, b, c, a T   , b T   , c T   } |
|                                   1,1     1,2     1,3  |
|                                                        |
|o7 : DGAlgebra                                          |
+--------------------------------------------------------+
|i8 : numgens B2.natural == numgens B.natural            |
|                                                        |
|o8 = true                                               |
+--------------------------------------------------------+

Over a non-c.i., higher deviations are nontrivial and acyclicClosure adjoins
further generators at each stage. Tallying by hom-degree gives the deviation
sequence of the ring (excluding hom-degree 0, where the ring itself sits):

+-----------------------------------------------------------------------------+
|i9 : S = QQ[x, y] / ideal(x^2, x*y, y^2)                                     |
|                                                                             |
|o9 = S                                                                       |
|                                                                             |
|o9 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i10 : C = acyclicClosure(koszulComplexDGA S, EndDegree => 3)                 |
|                                                                             |
|o10 = {Ring => S                                                             |
|       Underlying algebra => S[T   ..T   , T   ..T   , T   ..T   ,           |
|                                1,1   1,2   2,1   2,3   3,1   3,2            |
|       Differential => {x, y, x*T   , y*T   , y*T   , -x*T   T   ,           |
|                                 1,1     1,2     1,1      1,1 1,2            |
|                                                                             |
|o10 : DGAlgebra                                                              |
|-----------------------------------------------------------------------------|
|                                                   }                         |
|T   ..T   ]                                                                  |
| 4,1   4,3                                                                   |
|-y*T   T   , -y*T   T   , -y*T   T   , -y*T   T   }                          |
|    1,1 1,2      1,2 2,1      1,1 2,1      1,1 2,2                           |
+-----------------------------------------------------------------------------+
|i11 : tally apply(C.Degrees, d -> first d)                                   |
|                                                                             |
|o11 = Tally{1 => 2}                                                          |
|            2 => 3                                                           |
|            3 => 2                                                           |
|            4 => 3                                                           |
|                                                                             |
|o11 : Tally                                                                  |
+-----------------------------------------------------------------------------+

The hom-degree-1 count of 2 comes from the two Koszul exterior generators (one
per variable of S); hom-degree 2 has three polynomial generators killing the
three relations; and hom-degrees 3 and beyond have nontrivial deviations,
signaling that S is not a complete intersection.  Over a complete intersection,
all hom-degrees >= 3 would be empty.

To choose a different base symbol for the newly adjoined generators, use the
Variable option.  Existing generators of A keep their names:

+------------------------------------------------------------+
|i12 : D = acyclicClosure(A, EndDegree => 2, Variable => "U")|
|                                                            |
|o12 = {Ring => R                                        }   |
|       Underlying algebra => R[T   ..T   , U   ..U   ]      |
|                                1,1   1,3   2,1   2,3       |
|                                  2       2       2         |
|       Differential => {a, b, c, a T   , b T   , c T   }    |
|                                    1,1     1,2     1,3     |
|                                                            |
|o12 : DGAlgebra                                             |
+------------------------------------------------------------+
|i13 : gens D.natural                                        |
|                                                            |
|o13 = {T   , T   , T   , U   , U   , U   }                  |
|        1,1   1,2   1,3   2,1   2,2   2,3                   |
|                                                            |
|o13 : List                                                  |
+------------------------------------------------------------+

Caveat
======

For a DG algebra A whose degree-zero part already has inhomogeneous structure
(e.g. one built via freeDGAlgebra, with a hand-written
differential that is not square-zero), the package assumes d^2 = 0 without
checking; the resulting acyclicClosure is only meaningful when this holds.

See also
========

  * acyclicClosure(Ring) -- Tate's acyclic
    closure of the residue field, starting from the Koszul complex
  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree
  * adjoinVariables -- Extend a DG algebra by a
    user-chosen list of cycles to be killed
  * minimalModel -- Build the minimal DG algebra
    resolution of a quotient ring
  * koszulComplexDGA -- The Koszul complex on the
    variables of a ring, as a DG algebra
  * StartDegree -- Option to specify the first homological
    degree processed by an iterative DG construction
  * EndDegree -- Option to specify the last homological
    degree processed by an iterative DG construction

Ways to use acyclicClosure:
===========================

  * "acyclicClosure(DGAlgebra)"
  * acyclicClosure(Ring) -- Tate's acyclic
    closure of the residue field, starting from the Koszul complex

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1449:0.

acyclicClosure(...,EndDegree=>...) -- Option to specify the degree to stop computing the acyclic closure
********************************************************************************************************

  * Usage:
        A =  acyclicClosure(B,EndDegree=>n)
  * Inputs:
      * B, an instance of the type DGAlgebra,
      * n, an integer (Macaulay2Doc),

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

All generators of the acyclic closure will be found up to homological degree n.
Note that B can be an ordinary ring, a factor ring of a polynomial ring,
treated as a DGAlgebra generated in homological degree 0, as in the following
example:

The default value of EndDegree is 3.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[x,y,z,w]/(ideal"x3,y3,z3,x2yz")                              |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : acyclicClosure R                                                        |
|                                                                             |
|o2 = {Ring => R                                                              |
|      Underlying algebra => R[T   ..T   , T   ..T   , T   ..T   ]            |
|                               1,1   2,4   3,1   3,3   4,1   4,6             |
|                                    2       2       2                        |
|      Differential => {x, y, z, w, x T   , y T   , z T   , x*y*z*T   ,       |
|                                      1,1     1,2     1,3         1,1        |
|                                                                             |
|o2 : DGAlgebra                                                               |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|           2       2       2       2        2                                |
|y*z*T   , z T   , y T   , z T   , y T   , -x T   T   , -x*y*z*T   T   ,      |
|     2,1     2,4     2,4     3,1     3,1      1,1 2,4          1,1 2,3       |
|-----------------------------------------------------------------------------|
|                                 }                                           |
|                                                                             |
|                                                                             |
|                  2        2                                                 |
|-x*y*z*T   T   , y T    - z T   }                                            |
|        1,1 2,2     3,2      3,3                                             |
+-----------------------------------------------------------------------------+
|i3 : acyclicClosure(R,EndDegree => 3)                                        |
|                                                                             |
|o3 = {Ring => R                                                              |
|      Underlying algebra => R[T   ..T   , T   ..T   , T   ..T   ]            |
|                               1,1   2,4   3,1   3,3   4,1   4,6             |
|                                    2       2       2                        |
|      Differential => {x, y, z, w, x T   , y T   , z T   , x*y*z*T   ,       |
|                                      1,1     1,2     1,3         1,1        |
|                                                                             |
|o3 : DGAlgebra                                                               |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|           2       2       2       2        2                                |
|y*z*T   , z T   , y T   , z T   , y T   , -x T   T   , -x*y*z*T   T   ,      |
|     2,1     2,4     2,4     3,1     3,1      1,1 2,4          1,1 2,3       |
|-----------------------------------------------------------------------------|
|                                 }                                           |
|                                                                             |
|                                                                             |
|                  2        2                                                 |
|-x*y*z*T   T   , y T    - z T   }                                            |
|        1,1 2,2     3,2      3,3                                             |
+-----------------------------------------------------------------------------+

Functions with optional argument named EndDegree:
=================================================

  * acyclicClosure(...,EndDegree=>...)
    -- Option to specify
    the degree to stop computing the acyclic closure
  * isAcyclic(...,EndDegree=>...)
    -- Option to specify the
    degree to finish checking acyclicity
  * killCycles(...,EndDegree=>...)
    -- Last homological
    degree processed by killCycles
  * "liftToDGMap(...,EndDegree=>...)" -- see liftToDGMap, --
    Lift a ring homomorphism in degree zero to a DG algebra morphism
  * "liftToDGModuleMap(...,EndDegree=>...)" -- see liftToDGModuleMap,
    -- Lift an image of hom-degree-0 generators to a full
    DGModuleMap
  * "minimalModel(...,EndDegree=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * minimalSemifreeResolution(...,EndDegree=>...)
    -- Option
    to specify the last degree at which minimalSemifreeResolution kills cycles
  * semifreeResolution(...,EndDegree=>...)
    -- Option to
    specify the last degree at which semifreeResolution kills cycles
  * "toComplexMap(...,EndDegree=>...)" -- see toComplexMap,
    -- Construct the ComplexMap associated to a DGAlgebraMap

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

  * Default value: 3
  * Function: acyclicClosure, -- Tate's construction of a
    semifree acyclic DG algebra extension
  * Option key: EndDegree, -- Option to specify the last
    homological degree processed by an iterative DG construction
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9470:0.

acyclicClosure(...,StartDegree=>...) -- Option to specify the degree to start computing the acyclic closure.
************************************************************************************************************

  * Usage:
        acyclicClosure(...,StartDegree=>n)

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

The default value is 1.

Functions with optional argument named StartDegree:
===================================================

  * acyclicClosure(...,StartDegree=>...)
    -- Option to
    specify the degree to start computing the acyclic closure.
  * getGenerators(...,StartDegree=>...)
    -- First homological
    degree in which to search for new algebra generators
  * killCycles(...,StartDegree=>...)
    -- First homological
    degree from which killCycles begins searching for cycles
  * "minimalModel(...,StartDegree=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * minimalSemifreeResolution(...,StartDegree=>...),
    --
    Option to specify the degree at which minimalSemifreeResolution starts
    killing cycles
  * semifreeResolution(...,StartDegree=>...)
    -- Option to
    specify the degree at which semifreeResolution starts killing cycles

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

  * Default value: 1
  * Function: acyclicClosure, -- Tate's construction of a
    semifree acyclic DG algebra extension
  * Option key: StartDegree, -- Option to specify the first
    homological degree processed by an iterative DG construction
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9447:0.

acyclicClosure(...,Variable=>...) -- Option to name the DG algebra generators adjoined during acyclic closure
*************************************************************************************************************

  * Usage:
        acyclicClosure(..., Variable => "T")

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

As acyclicClosure, iteratively kills cycles,
it adjoins new DG algebra generators indexed by T_(i, j) (or the
given base name). Use the Variable option to control that base name.

See also
========

  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension
  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree
  * Variable (Macaulay2Doc) -- an optional argument

Functions with optional argument named Variable:
================================================

  * acyclicClosure(...,Variable=>...)
    -- Option to name the
    DG algebra generators adjoined during acyclic closure
  * adjoinVariables(...,Variable=>...)
    -- Option to name the
    DG algebra generators adjoined by adjoinVariables
  * "freeDGAlgebra(...,Variable=>...)" -- see freeDGAlgebra,
    -- Construct a free DG algebra with given generator degrees
  * "GF(...,Variable=>...)" -- see GF (Macaulay2Doc), -- make a finite
    field
  * "Grassmannian(...,Variable=>...)" -- see Grassmannian (Macaulay2Doc),
    -- compute the ideal of the Grassmannian of
    linear subspaces of a vector space
  * idealizer(...,Variable=>...) (IntegralClosure)
    -- Sets
    the name of the indexed variables introduced in computing the endomorphism
    ring Hom(J,J).
  * integralClosure(...,Variable=>...) (IntegralClosure),
    --
    set the base letter for the indexed variables introduced while computing
    the integral closure
  * killCycles(...,Variable=>...)
    -- Option to name the DG
    algebra generators adjoined by killCycles
  * "koszulComplexDGA(...,Variable=>...)" -- see koszulComplexDGA,
    -- The Koszul complex on the variables of a ring, as a DG
    algebra
  * makeS2(...,Variable=>...) (IntegralClosure)
    -- Sets the
    name of the indexed variables introduced in computing the S2-ification.
  * "minimalModel(...,Variable=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * normalCone(Ideal,RingElement,Variable=>...) (missing documentation)
  * normalCone(Ideal,Variable=>...) (missing documentation)
  * "ringFromFractions(...,Variable=>...)" -- see ringFromFractions (IntegralClosure),
    -- find presentation for f.g. ring
  * "Schubert(...,Variable=>...)" -- see Schubert (Macaulay2Doc),
    -- compute the Plücker ideal of a Schubert variety

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

  * Default value: null
  * Function: acyclicClosure, -- Tate's construction of a
    semifree acyclic DG algebra extension
  * Option key: Variable (Macaulay2Doc), -- an optional argument
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9593:0.

acyclicClosure(Ring) -- Tate's acyclic closure of the residue field, starting from the Koszul complex
*****************************************************************************************************

  * Function: acyclicClosure,
  * Usage:
        A = acyclicClosure R
        A = acyclicClosure(R, EndDegree => n)
  * Inputs:
      * R, a ring (Macaulay2Doc), A local or graded ring (in
        practice, a quotient of a polynomial ring by a homogeneous ideal).
  * Optional inputs (Macaulay2Doc),:
      * EndDegree,
        => ..., default value 3, Option to specify the degree to stop computing
        the acyclic closure
      * StartDegree,
        => ..., default value 1, Option to specify the degree to start
        computing the acyclic closure.
      * Variable, =>
        ..., default value null, Option to name the DG algebra generators
        adjoined during acyclic closure
  * Outputs:
      * A, an instance of the type DGAlgebra, A semifree DG
        algebra over R whose degree-zero homology is R/m = R_0 (the residue
        field, or more generally R/ see ideal(Ring) (Macaulay2Doc),
        R) and whose positive homology is killed
        through hom-degree EndDegree.

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

This form is shorthand for acyclicClosure(koszulComplexDGA R, ...): the Koszul
complex on a chosen generating set of the maximal/irrelevant ideal is used as
the starting DG algebra, and acyclicClosure(DGAlgebra),
iteratively adjoins new generators to kill homology up to EndDegree.  The
output is a truncation of Avramov's acyclic closure of R over itself --
equivalently, a free DG algebra resolution of the residue field in hom-degrees
0 through EndDegree.

Variable convention.  The hom-degree-1 exterior generators come from
koszulComplexDGA, and are named T_(1,j), one for each
generator of the maximal/irrelevant ideal.  Higher generators (adjoined by
killCycles, at each stage) are named T_(n,j), with n the
homological degree and j a 1-indexed counter.  Generators of odd hom-degree are
exterior; generators of even hom-degree are polynomial.  Pass Variable => "S"
(or any string/symbol) to rename the base.

+--------------------------------------------------------------------+
|i1 : R = ZZ/101[a, b, c, d] / ideal(a^3, b^3, c^4 - d^3)            |
|                                                                    |
|o1 = R                                                              |
|                                                                    |
|o1 : QuotientRing                                                   |
+--------------------------------------------------------------------+
|i2 : A = acyclicClosure(R, EndDegree => 3)                          |
|                                                                    |
|o2 = {Ring => R                                                    }|
|      Underlying algebra => R[T   ..T   , T   ..T   ]               |
|                               1,1   1,4   2,1   2,3                |
|                                    2       2       3        2      |
|      Differential => {a, b, c, d, a T   , b T   , c T    - d T   } |
|                                      1,1     1,2     1,3      1,4  |
|                                                                    |
|o2 : DGAlgebra                                                      |
+--------------------------------------------------------------------+
|i3 : tally apply(A.Degrees, d -> first d)                           |
|                                                                    |
|o3 = Tally{1 => 4}                                                  |
|           2 => 3                                                   |
|                                                                    |
|o3 : Tally                                                          |
+--------------------------------------------------------------------+
|i4 : take(flatten entries matrix A.diff, numgens A.natural)         |
|                                                                    |
|                   2       2       3        2                       |
|o4 = {a, b, c, d, a T   , b T   , c T    - d T   }                  |
|                     1,1     1,2     1,3      1,4                   |
|                                                                    |
|o4 : List                                                           |
+--------------------------------------------------------------------+

Four hom-degree-1 exterior generators T_(1,1), ..., T_(1,4) (one per variable
of R) and three hom-degree-2 polynomial generators (one for each defining
relation, since R is a complete intersection of codimension 3).  In the
resulting DG algebra the residue field has been resolved through hom-degree 3.

For a complete intersection, the Koszul complex already has zero higher
homology beyond what the Tate polynomial closure kills at hom-degree 2, so the
number of generators stabilizes quickly:

+--------------------------------------------------------+
|i5 : S = QQ[x, y, z] / ideal(x^2, y^2, z^2)             |
|                                                        |
|o5 = S                                                  |
|                                                        |
|o5 : QuotientRing                                       |
+--------------------------------------------------------+
|i6 : C = acyclicClosure(S, EndDegree => 4)              |
|                                                        |
|o6 = {Ring => S                                        }|
|      Underlying algebra => S[T   ..T   ]               |
|                               1,1   2,3                |
|      Differential => {x, y, z, x*T   , y*T   , z*T   } |
|                                   1,1     1,2     1,3  |
|                                                        |
|o6 : DGAlgebra                                          |
+--------------------------------------------------------+
|i7 : tally apply(C.Degrees, d -> first d)               |
|                                                        |
|o7 = Tally{1 => 3}                                      |
|           2 => 3                                       |
|                                                        |
|o7 : Tally                                              |
+--------------------------------------------------------+

For a non-c.i., further deviations appear:

+-----------------------------------------------------------------------------+
|i8 : T = QQ[x, y] / ideal(x^2, x*y, y^2)                                     |
|                                                                             |
|o8 = T                                                                       |
|                                                                             |
|o8 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i9 : D = acyclicClosure(T, EndDegree => 3)                                   |
|warning: clearing value of symbol T to allow access to subscripted variables |
|       : debug with expression   debug 6944   or with command line option    |
|                                                                             |
|o9 = {Ring => T                                                              |
|      Underlying algebra => T[T   ..T   , T   ..T   , T   ..T   , T   ..T    |
|                               1,1   1,2   2,1   2,3   3,1   3,2   4,1   4,3 |
|      Differential => {x, y, x*T   , y*T   , y*T   , -x*T   T   , -y*T   T   |
|                                1,1     1,2     1,1      1,1 1,2      1,1 1, |
|                                                                             |
|o9 : DGAlgebra                                                               |
|-----------------------------------------------------------------------------|
| based on it                                                                 |
|--debug 6944                                                                 |
|                                                                             |
|                                         }                                   |
|]                                                                            |
|                                                                             |
| , -y*T   T   , -y*T   T   , -y*T   T   }                                    |
|2      1,2 2,1      1,1 2,1      1,1 2,2                                     |
+-----------------------------------------------------------------------------+
|i10 : tally apply(D.Degrees, d -> first d)                                   |
|                                                                             |
|o10 = Tally{1 => 2}                                                          |
|            2 => 3                                                           |
|            3 => 2                                                           |
|            4 => 3                                                           |
|                                                                             |
|o10 : Tally                                                                  |
+-----------------------------------------------------------------------------+

See also
========

  * acyclicClosure(DGAlgebra) -- Tate's construction of
    a semifree acyclic DG algebra extension
  * koszulComplexDGA -- The Koszul complex on the
    variables of a ring, as a DG algebra
  * minimalModel -- Build the minimal DG algebra
    resolution of a quotient ring
  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree
  * StartDegree -- Option to specify the first homological
    degree processed by an iterative DG construction
  * EndDegree -- Option to specify the last homological
    degree processed by an iterative DG construction

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

  * acyclicClosure(Ring) -- Tate's acyclic
    closure of the residue field, starting from the Koszul complex
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1521:0.

adjoinVariables -- Extend a DG algebra by a user-chosen list of cycles to be killed
***********************************************************************************

  * Usage:
        B = adjoinVariables(A, cycleList)
        B = adjoinVariables(A, cycleList, Variable => "U")
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * cycleList, a list (Macaulay2Doc), Homogeneous cycles of A,
        i.e.\ elements z in A.natural with (A.diff)(z) = 0 (no check is
        performed).  Each cycle must have the same multi-degree shape as
        A.Degrees.
  * Optional inputs (Macaulay2Doc),:
      * Variable,
        => a string (Macaulay2Doc), default value null, Base name
        for the newly adjoined generators.  Defaults to the base symbol already
        used by A, or "T" if A has no generators.
  * Outputs:
      * B, an instance of the type DGAlgebra, A semifree
        extension of A with one new generator per entry of cycleList.  The new
        generator for a cycle z of hom-degree n has hom-degree n + 1 and
        differential z.

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

Whereas killCycles, chooses representatives of a basis of the
first nonzero homology of A automatically, adjoinVariables lets the user
specify exactly which cycles become boundaries.  This is the primitive used by
acyclicClosure, killCycles, and
minimalModel, but can also be called directly to build DG
algebra resolutions by hand.

Variable convention.  The new generators extend the existing doubly-indexed
naming scheme base_(i, j): for each adjoined cycle of hom-degree n, a new
generator named base_(n+1, k) is created, where k continues the 1-indexed
counter already in use at hom-degree n + 1 in A.  Existing generator names are
preserved verbatim. Passing Variable => "U" switches the base symbol for the
new generators only:

+--------------------------------------------------+
|i1 : R = ZZ/101[a, b, c] / ideal(a^3, b^3, c^3)   |
|                                                  |
|o1 = R                                            |
|                                                  |
|o1 : QuotientRing                                 |
+--------------------------------------------------+
|i2 : A = koszulComplexDGA R                       |
|                                                  |
|o2 = {Ring => R                          }        |
|      Underlying algebra => R[T   ..T   ]         |
|                               1,1   1,3          |
|      Differential => {a, b, c}                   |
|                                                  |
|o2 : DGAlgebra                                    |
+--------------------------------------------------+
|i3 : z = a^2 * (gens A.natural)_0                 |
|                                                  |
|      2                                           |
|o3 = a T                                          |
|        1,1                                       |
|                                                  |
|o3 : R[T   ..T   ]                                |
|        1,1   1,3                                 |
+--------------------------------------------------+
|i4 : polyDifferential(A, z) == 0                  |
|                                                  |
|o4 = true                                         |
+--------------------------------------------------+
|i5 : B = adjoinVariables(A, {z})                  |
|                                                  |
|o5 = {Ring => R                                }  |
|      Underlying algebra => R[T   ..T   , T   ]   |
|                               1,1   1,3   2,1    |
|                                 2                |
|      Differential => {a, b, c, a T   }           |
|                                   1,1            |
|                                                  |
|o5 : DGAlgebra                                    |
+--------------------------------------------------+
|i6 : gens B.natural                               |
|                                                  |
|o6 = {T   , T   , T   , T   }                     |
|       1,1   1,2   1,3   2,1                      |
|                                                  |
|o6 : List                                         |
+--------------------------------------------------+
|i7 : B' = adjoinVariables(A, {z}, Variable => "U")|
|                                                  |
|o7 = {Ring => R                                }  |
|      Underlying algebra => R[T   ..T   , U   ]   |
|                               1,1   1,3   2,1    |
|                                 2                |
|      Differential => {a, b, c, a T   }           |
|                                   1,1            |
|                                                  |
|o7 : DGAlgebra                                    |
+--------------------------------------------------+
|i8 : gens B'.natural                              |
|                                                  |
|o8 = {T   , T   , T   , U   }                     |
|       1,1   1,2   1,3   2,1                      |
|                                                  |
|o8 : List                                         |
+--------------------------------------------------+

Killing a single cycle lowers the size of the corresponding homology:

+-------------------------------------------------+
|i9 : apply(3, i -> numgens prune homology(i, A)) |
|                                                 |
|o9 = {1, 3, 3}                                   |
|                                                 |
|o9 : List                                        |
+-------------------------------------------------+
|i10 : apply(3, i -> numgens prune homology(i, B))|
|                                                 |
|o10 = {1, 2, 1}                                  |
|                                                 |
|o10 : List                                       |
+-------------------------------------------------+

Over a non-c.i.\ example with a non-regular relation, one can inspect the first
homology, pick a representative, and kill just that class (leaving other H_1
classes intact):

+-----------------------------------------------------------+
|i11 : S = ZZ/101[a, b, c, d] / ideal(a^3, b^3, c^3 - d^4)  |
|                                                           |
|o11 = S                                                    |
|                                                           |
|o11 : QuotientRing                                         |
+-----------------------------------------------------------+
|i12 : AS = koszulComplexDGA S                              |
|                                                           |
|o12 = {Ring => S                          }                |
|       Underlying algebra => S[T   ..T   ]                 |
|                                1,1   1,4                  |
|       Differential => {a, b, c, d}                        |
|                                                           |
|o12 : DGAlgebra                                            |
+-----------------------------------------------------------+
|i13 : prune homology(1, AS)                                |
|                                                           |
|o13 = cokernel | d c b a 0 0 0 0 0 0 0 0 |                 |
|               | 0 0 0 0 d c b a 0 0 0 0 |                 |
|               | 0 0 0 0 0 0 0 0 d c b a |                 |
|                                                           |
|                             3                             |
|o13 : S-module, quotient of S                              |
+-----------------------------------------------------------+
|i14 : BS = adjoinVariables(AS, {a^2 * (gens AS.natural)_0})|
|                                                           |
|o14 = {Ring => S                                }          |
|       Underlying algebra => S[T   ..T   , T   ]           |
|                                1,1   1,4   2,1            |
|                                     2                     |
|       Differential => {a, b, c, d, a T   }                |
|                                       1,1                 |
|                                                           |
|o14 : DGAlgebra                                            |
+-----------------------------------------------------------+
|i15 : prune homology(1, BS)                                |
|                                                           |
|o15 = cokernel | d c b a 0 0 0 0 |                         |
|               | 0 0 0 0 d c b a |                         |
|                                                           |
|                             2                             |
|o15 : S-module, quotient of S                              |
+-----------------------------------------------------------+

Caveat
======

The package does not verify that the supplied elements are actually cycles;
passing a non-cycle produces a malformed DG algebra. Use polyDifferential(A, z)
== 0 to check before calling (the shorthand (A.diff)(z) applies A.diff as a
ring map, which only agrees with the differential on monomials that contain at
most one algebra generator and hence is not a valid cycle check for products).

See also
========

  * DGAlgebra -- The class of all DGAlgebras
  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree
  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension
  * minimalModel -- Build the minimal DG algebra
    resolution of a quotient ring
  * setDiff -- Install or replace the differential on a DG
    algebra

Ways to use adjoinVariables:
============================

  * "adjoinVariables(DGAlgebra,List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8086:0.

adjoinVariables(...,Variable=>...) -- Option to name the DG algebra generators adjoined by adjoinVariables
**********************************************************************************************************

  * Usage:
        adjoinVariables(..., Variable => "T")

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

See adjoinVariables, adjoins a new DG generator for each
cycle in its input list. The Variable option specifies the base name used for
these new generators.

See also
========

  * adjoinVariables -- Extend a DG algebra by a
    user-chosen list of cycles to be killed
  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree

Functions with optional argument named Variable:
================================================

  * acyclicClosure(...,Variable=>...)
    -- Option to name the
    DG algebra generators adjoined during acyclic closure
  * adjoinVariables(...,Variable=>...)
    -- Option to name the
    DG algebra generators adjoined by adjoinVariables
  * "freeDGAlgebra(...,Variable=>...)" -- see freeDGAlgebra,
    -- Construct a free DG algebra with given generator degrees
  * "GF(...,Variable=>...)" -- see GF (Macaulay2Doc), -- make a finite
    field
  * "Grassmannian(...,Variable=>...)" -- see Grassmannian (Macaulay2Doc),
    -- compute the ideal of the Grassmannian of
    linear subspaces of a vector space
  * idealizer(...,Variable=>...) (IntegralClosure)
    -- Sets
    the name of the indexed variables introduced in computing the endomorphism
    ring Hom(J,J).
  * integralClosure(...,Variable=>...) (IntegralClosure),
    --
    set the base letter for the indexed variables introduced while computing
    the integral closure
  * killCycles(...,Variable=>...)
    -- Option to name the DG
    algebra generators adjoined by killCycles
  * "koszulComplexDGA(...,Variable=>...)" -- see koszulComplexDGA,
    -- The Koszul complex on the variables of a ring, as a DG
    algebra
  * makeS2(...,Variable=>...) (IntegralClosure)
    -- Sets the
    name of the indexed variables introduced in computing the S2-ification.
  * "minimalModel(...,Variable=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * normalCone(Ideal,RingElement,Variable=>...) (missing documentation)
  * normalCone(Ideal,Variable=>...) (missing documentation)
  * "ringFromFractions(...,Variable=>...)" -- see ringFromFractions (IntegralClosure),
    -- find presentation for f.g. ring
  * "Schubert(...,Variable=>...)" -- see Schubert (Macaulay2Doc),
    -- compute the Plücker ideal of a Schubert variety

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

  * Default value: null
  * Function: adjoinVariables, -- Extend a DG algebra by
    a user-chosen list of cycles to be killed
  * Option key: Variable (Macaulay2Doc), -- an optional argument
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9575:0.

ambient -- Accessors for the ambient object, inclusion, projection, and killed submodule
****************************************************************************************

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

These accessors navigate between the DG types in the DGModule / DGSubmodule /
DGQuotientModule hierarchy:

ambient on a DGIdeal, returns the enclosing DGAlgebra,;
on a DGSubmodule, or DGQuotientModule,
it returns the enclosing DGModule.

inclusion on a DGSubmodule, S returns the DGModuleMap,
S → ambient(S).

projection on a DGQuotientModule, Q returns the
DGModuleMap, ambient(Q) → Q.

subDGModule on a DGQuotientModule, Q returns the
DGSubmodule, that was killed to form Q.

+---------------------------------------+
|i1 : R = ZZ/101[x]                     |
|                                       |
|o1 = R                                 |
|                                       |
|o1 : PolynomialRing                    |
+---------------------------------------+
|i2 : A = koszulComplexDGA R            |
|                                       |
|o2 = {Ring => R                    }   |
|      Underlying algebra => R[T   ]    |
|                               1,1     |
|      Differential => {x}              |
|                                       |
|o2 : DGAlgebra                         |
+---------------------------------------+
|i3 : M = freeDGModule(A, {0})          |
|                                       |
|o3 = {Base ring => R               }   |
|      DG algebra => R[T   ]            |
|                       1,1             |
|                                 1     |
|      Natural module => (R[T   ])      |
|                            1,1        |
|      Generator degrees => {{0, 0}}    |
|      Differentials on gens => {0}     |
|                                       |
|o3 : DGModule                          |
+---------------------------------------+
|i4 : S = dgSubmodule(M, id_(M.natural))|
|                                       |
|o4 = DGSubmodule of ambient DGModule   |
|     Degrees  => {{0, 0}}              |
|                          1            |
|     natural  => (R[T   ])             |
|                     1,1               |
|     inclusion => | 1 |                |
|                                       |
|o4 : DGSubmodule                       |
+---------------------------------------+
|i5 : Q = M / S                         |
|                                       |
|o5 = DGQuotientModule Q = M / S        |
|     Q.natural = cokernel | 1 |        |
|     Degrees   = {{0, 0}}              |
|                                       |
|o5 : DGQuotientModule                  |
+---------------------------------------+
|i6 : ambient S === M                   |
|                                       |
|o6 = true                              |
+---------------------------------------+
|i7 : ambient Q === M                   |
|                                       |
|o7 = true                              |
+---------------------------------------+
|i8 : source inclusion S === S          |
|                                       |
|o8 = true                              |
+---------------------------------------+
|i9 : target inclusion S === M          |
|                                       |
|o9 = true                              |
+---------------------------------------+
|i10 : source projection Q === M        |
|                                       |
|o10 = true                             |
+---------------------------------------+
|i11 : target projection Q === Q        |
|                                       |
|o11 = true                             |
+---------------------------------------+
|i12 : subDGModule Q === S              |
|                                       |
|o12 = true                             |
+---------------------------------------+

For a DGIdeal the analogous accessor returns the DGAlgebra:

+-------------------------------------+
|i13 : I = dgIdeal(A, {x_(A.natural)})|
|                                     |
|o13 = DGIdeal of R[T   ]             |
|                    1,1              |
|      generators => | x |            |
|                                     |
|o13 : DGIdeal                        |
+-------------------------------------+
|i14 : ambient I === A                |
|                                     |
|o14 = true                           |
+-------------------------------------+

See also
========

  * Building DG modules, submodules, and quotients
    -- The DGModule / DGSubmodule /
    DGQuotientModule hierarchy and its constructors
  * DGSubmodule -- The class of d-closed submodules of a DG
    module
  * DGQuotientModule -- The class of quotient DG
    modules M / S
  * DGIdeal -- The class of d-closed graded ideals of a DG
    algebra

Ways to use ambient:
====================

  * "ambient(DGIdeal)"
  * "ambient(DGQuotientModule)"
  * "ambient(DGSubmodule)"
  * ambient(GaloisField) (Macaulay2Doc), --
    corresponding quotient ring
  * ambient(Matrix) (Macaulay2Doc) -- get the map
    between the ambient free modules
  * ambient(Module) (Macaulay2Doc) -- ambient free
    module
  * "ambient(PolynomialRing)" -- see ambient(Ring) (Macaulay2Doc),
    -- ambient polynomial ring
  * "ambient(QuotientRing)" -- see ambient(Ring) (Macaulay2Doc),
    -- ambient polynomial ring
  * ambient(Ring) (Macaulay2Doc) -- ambient polynomial
    ring

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:3343:0.

AssertWellDefined -- Option to verify that a constructed DG algebra map respects differentials
**********************************************************************************************

  * Usage:
        liftToDGMap(..., AssertWellDefined => true)
        toComplexMap(..., AssertWellDefined => true)

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

When set to true, the constructor checks that the output DGAlgebraMap,
or the resulting ComplexMap (Complexes),
actually commutes with the differentials up to the working degree.  This is a
false by default because the check can be expensive for large acyclic closures;
set it to true when debugging a DG map that behaves unexpectedly.

See also
========

  * liftToDGMap -- Lift a ring homomorphism in degree zero
    to a DG algebra morphism
  * toComplexMap -- Construct the ComplexMap associated to
    a DGAlgebraMap
  * dgAlgebraMap -- Define a DG algebra map between DG
    algebras.

Functions with optional argument named AssertWellDefined:
=========================================================

  * "toComplexMap(...,AssertWellDefined=>...)" -- see toComplexMap,
    -- Construct the ComplexMap associated to a DGAlgebraMap

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

The object AssertWellDefined, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9304:0.

blockDiff -- prepares a map for display
***************************************

  * Usage:
        X = blockDiff(A,n)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * n, an integer (Macaulay2Doc),
  * Outputs:
      * X, a matrix (Macaulay2Doc), map between labeled direct
        sums

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

Use displayBlockDiff, to display the blocks in various
ways.

See also
========

  * displayBlockDiff -- Shows natural decomposition of
    a map in the Tate resolution

Ways to use blockDiff:
======================

  * "blockDiff(DGAlgebra,ZZ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9993:0.

cycles -- Chosen cycle representatives for homology generators of a DG algebra
******************************************************************************

  * Usage:
        A.cycles

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

When acyclicClosure, killCycles, or
homologyAlgebra, adjoin new generators to kill homology
of a DG algebra A, the chosen cycle representatives are cached on the output so
the exact Tate construction can be inspected afterwards.  The key is A.cycles
on a DG algebra, or HA.cache.cycles on the output of homologyAlgebra.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a, b, c, d] / ideal(a^3, b^4, c^5, d^6)                      |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o2 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,4                                     |
|      Differential => {a, b, c, d}                                           |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : apply(maxDegree A + 1, i -> numgens prune homology(i, A))               |
|                                                                             |
|o3 = {1, 4, 6, 4, 1}                                                         |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : HA = homologyAlgebra A                                                  |
|Finding easy relations           :  -- used 0.0250882s (cpu); 0.0222818s     |
|                                                                             |
|o4 = HA                                                                      |
|                                                                             |
|o4 : PolynomialRing, 4 skew commutative variable(s)                          |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i5 : numgens HA                                                              |
|                                                                             |
|o5 = 4                                                                       |
+-----------------------------------------------------------------------------+
|i6 : HA.cache.cycles                                                         |
|                                                                             |
|       2       3       4       5                                             |
|o6 = {a T   , b T   , c T   , d T   }                                        |
|         1,1     1,2     1,3     1,4                                         |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

The entries of HA.cache.cycles are elements of A.natural: cycles chosen to
represent the generators of HA as an algebra.  These are the same
representatives that would be used as the differentials of newly adjoined
generators in acyclicClosure.

See also
========

  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.
  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension
  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree

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

The object cycles, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1232:0.

deviations -- Computes the deviations of the input ring, complex, or power series.
**********************************************************************************

  * Usage:
        devTally = deviations(R)
  * Inputs:
      * R, a ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * DegreeLimit,
        => ..., default value 3, Maximum homological degree to which deviations
        are computed
  * Outputs:
      * devTally, a tally (Macaulay2Doc),

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

This command computes the deviations of a Ring (Macaulay2Doc), a
Complex (Complexes), or a power series in the form of a
RingElement (Macaulay2Doc). The deviations are the same as the
degrees of the generators of the acyclic closure of R, or the degrees of the
generators of the Tor algebra of R.  This function takes an option called Limit
(default value 3) that specifies the largest deviation to compute.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c,d]/ideal {a^3,b^3,c^3,d^3}                             |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : deviations(R)                                                           |
|                                                                             |
|o2 = HashTable{(1, {1}) => 4}                                                |
|               (2, {3}) => 4                                                 |
|                                                                             |
|o2 : HashTable                                                               |
+-----------------------------------------------------------------------------+
|i3 : deviations(R,DegreeLimit=>4)                                            |
|                                                                             |
|o3 = HashTable{(1, {1}) => 4}                                                |
|               (2, {3}) => 4                                                 |
|                                                                             |
|o3 : HashTable                                                               |
+-----------------------------------------------------------------------------+
|i4 : S = R/ideal{a^2*b^2*c^2*d^2}                                            |
|                                                                             |
|o4 = S                                                                       |
|                                                                             |
|o4 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i5 : deviations(S,DegreeLimit=>4)                                            |
|                                                                             |
|o5 = HashTable{(1, {1}) => 4 }                                               |
|               (2, {3}) => 4                                                 |
|               (2, {8}) => 1                                                 |
|               (3, {9}) => 4                                                 |
|               (4, {10}) => 6                                                |
|               (4, {11}) => 4                                                |
|                                                                             |
|o5 : HashTable                                                               |
+-----------------------------------------------------------------------------+
|i6 : T = ZZ/101[a,b]/ideal {a^2-b^3}                                         |
|                                                                             |
|o6 = T                                                                       |
|                                                                             |
|o6 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i7 : deviations(T,DegreeLimit=>4)                                            |
|warning: clearing value of symbol T to allow access to subscripted           |
|       : debug with expression   debug 6944   or with command line           |
|                                                                             |
|o7 = HashTable{1 => 2}                                                       |
|               2 => 1                                                        |
|                                                                             |
|o7 : HashTable                                                               |
|-----------------------------------------------------------------------------|
|variables based on it                                                        |
|option   --debug 6944                                                        |
+-----------------------------------------------------------------------------+

Note that the deviations of T are not graded, since T is not graded.  When
calling deviations on a Complex, the zeroth free module must be cyclic, and
this is checked.  The same goes for the case of a RingElement.

+-------------------------------------------------------------------------+
|i8 : R = ZZ/101[a,b,c,d]/ideal {a^3,b^3,c^3,d^3}                         |
|                                                                         |
|o8 = R                                                                   |
|                                                                         |
|o8 : QuotientRing                                                        |
+-------------------------------------------------------------------------+
|i9 : A = degreesRing R                                                   |
|                                                                         |
|o9 = A                                                                   |
|                                                                         |
|o9 : PolynomialRing                                                      |
+-------------------------------------------------------------------------+
|i10 : kRes = freeResolution(coker vars R, LengthLimit => 4)              |
|                                                                         |
|       1      4      10      20      35                                  |
|o10 = R  <-- R  <-- R   <-- R   <-- R                                    |
|                                                                         |
|      0      1      2       3       4                                    |
|                                                                         |
|o10 : Complex                                                            |
+-------------------------------------------------------------------------+
|i11 : pSeries = poincareN kRes                                           |
|                                                                         |
|                    2 2     2 3     3 3      3 4    4 4      4 5      4 6|
|o11 = 1 + 4S*T  + 6S T  + 4S T  + 4S T  + 16S T  + S T  + 24S T  + 10S T |
|              0       0       0       0        0      0        0        0|
|                                                                         |
|o11 : ZZ[S, T ]                                                          |
|             0                                                           |
+-------------------------------------------------------------------------+
|i12 : devA = deviations(R,DegreeLimit=>5)                                |
|                                                                         |
|o12 = HashTable{(1, {1}) => 4}                                           |
|                (2, {3}) => 4                                            |
|                                                                         |
|o12 : HashTable                                                          |
+-------------------------------------------------------------------------+
|i13 : devB = deviations(kRes,DegreeLimit=>5)                             |
|                                                                         |
|o13 = HashTable{(1, {1}) => 4}                                           |
|                (2, {3}) => 4                                            |
|                                                                         |
|o13 : HashTable                                                          |
+-------------------------------------------------------------------------+
|i14 : devC = deviations(pSeries,degrees R, DegreeLimit=>5)               |
|                                                                         |
|o14 = HashTable{(1, {1}) => 4}                                           |
|                (2, {3}) => 4                                            |
|                                                                         |
|o14 : HashTable                                                          |
+-------------------------------------------------------------------------+
|i15 : devA === devB and devB === devC                                    |
|                                                                         |
|o15 = true                                                               |
+-------------------------------------------------------------------------+

Ways to use deviations:
=======================

  * "deviations(Complex)"
  * "deviations(Ring)"
  * "deviations(RingElement,List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8475:0.

deviations(...,DegreeLimit=>...) -- Maximum homological degree to which deviations are computed
***********************************************************************************************

  * Usage:
        deviations(..., DegreeLimit => n)

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

Bounds the homological degree of generators reported by deviations.
The default value is 3.

See also
========

  * deviations -- Computes the deviations of the input ring,
    complex, or power series.
  * deviationsToPoincare -- Computes the power
    series corresponding to a set of deviations.

Functions with optional argument named DegreeLimit:
===================================================

  * "compose(Module,Module,Module,DegreeLimit=>...)" -- see compose (Macaulay2Doc),
    -- composition as a pairing on Hom-modules
  * deviations(...,DegreeLimit=>...)
    -- Maximum homological
    degree to which deviations are computed
  * "deviationsToPoincare(...,DegreeLimit=>...)" -- see
    deviationsToPoincare, -- Computes the power series
    corresponding to a set of deviations.
  * "End(...,DegreeLimit=>...)" -- see End (Macaulay2Doc), -- module
    of endomorphisms
  * epicResolutionMap(...,DegreeLimit=>...) (missing documentation)
  * "gb(...,DegreeLimit=>...)" -- see gb (Macaulay2Doc), -- compute a
    Gröbner basis
  * getGenerators(...,DegreeLimit=>...)
    -- Last homological
    degree in which to search for algebra generators
  * "Hom(...,DegreeLimit=>...)" -- see Hom (Macaulay2Doc), -- module
    of homomorphisms
  * "homomorphism'(...,DegreeLimit=>...)" -- see homomorphism' (Macaulay2Doc),
    -- get the element of Hom from a homomorphism
  * kernel(...,DegreeLimit=>...) (Macaulay2Doc)
    -- stop after
    finding enough elements of a subring
  * "minimalBetti(...,DegreeLimit=>...)" -- see minimalBetti (Macaulay2Doc),
    -- minimal betti numbers of (the minimal free
    resolution of) a homogeneous ideal or module
  * normalCone(Ideal,DegreeLimit=>...) (missing documentation)
  * normalCone(Ideal,RingElement,DegreeLimit=>...) (missing documentation)
  * "freeResolution(...,DegreeLimit=>...)" -- see Options for free resolutions (Complexes),
    -- optional arguments
    for freeResolution
  * "pushForward(...,DegreeLimit=>...)" -- see
    pushForward(RingMap,Module) (Macaulay2Doc),
    -- compute the pushforward
    of a module along a ring map
  * quotient(...,DegreeLimit=>...) (missing documentation)
  * "resolutionMap(...,DegreeLimit=>...)" -- see resolutionMap (Complexes),
    -- map from a free resolution to the given
    complex
  * saturate(...,DegreeLimit=>...) (missing documentation)
  * "syz(...,DegreeLimit=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix

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

  * Default value: 3
  * Function: deviations, -- Computes the deviations of the
    input ring, complex, or power series.
  * Option key: DegreeLimit (Macaulay2Doc), -- an optional
    argument
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9750:0.

deviationsToPoincare -- Computes the power series corresponding to a set of deviations.
***************************************************************************************

  * Usage:
        pSeries = deviationsToPoincare(devHash)
  * Inputs:
      * devHash, a hash table (Macaulay2Doc), HashTable of the
        same form as the output from deviations,
  * Optional inputs (Macaulay2Doc),:
      * DegreeLimit => ..., default value 0
  * Outputs:
      * pSeries, a ring element (Macaulay2Doc),

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

This command takes a HashTable of the same form output from deviations,
and produces the Poincare series corresponding to it. The
(key,value) pairs must be of the form homologicalDegree=>number or
(homologicalDegree,internalDegree)=>number. Because

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c]/ideal{a^3,b^3,c^3}                                    |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : RDevs = deviations(R,DegreeLimit=>6)                                    |
|                                                                             |
|o2 = HashTable{(1, {1}) => 3}                                                |
|               (2, {3}) => 3                                                 |
|                                                                             |
|o2 : HashTable                                                               |
+-----------------------------------------------------------------------------+
|i3 : devPSeries = deviationsToPoincare(RDevs,DegreeLimit=>6)                 |
|                                                                             |
|        6 9      6 8      5 7     5 6     4 6     4 5     3 4    3 3     2 3 |
|o3 = 10S T  + 18S T  + 18S T  + 3S T  + 6S T  + 9S T  + 9S T  + S T  + 3S T  |
|          0        0        0       0       0       0       0      0       0 |
|     ------------------------------------------------------------------------|
|         2 2                                                                 |
|     + 3S T  + 3S*T  + 1                                                     |
|           0       0                                                         |
|                                                                             |
|     ZZ[S, T ]                                                               |
|            0                                                                |
|o3 : ---------                                                               |
|          7                                                                  |
|         S                                                                   |
+-----------------------------------------------------------------------------+
|i4 : pSeries = poincareN (freeResolution(coker vars R, LengthLimit=>6))      |
|                                                                             |
|                   2 2     2 3    3 3     3 4     4 5     4 6     5 6        |
|o4 = 1 + 3S*T  + 3S T  + 3S T  + S T  + 9S T  + 9S T  + 6S T  + 3S T  +      |
|             0       0       0      0       0       0       0       0        |
|     ------------------------------------------------------------------------|
|        5 7      6 8      6 9                                                |
|     18S T  + 18S T  + 10S T                                                 |
|          0        0        0                                                |
|                                                                             |
|o4 : ZZ[S, T ]                                                               |
|            0                                                                |
+-----------------------------------------------------------------------------+
|i5 : substitute(devPSeries,ring pSeries) == pSeries                          |
|                                                                             |
|o5 = false                                                                   |
+-----------------------------------------------------------------------------+

Ways to use deviationsToPoincare:
=================================

  * "deviationsToPoincare(HashTable)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8502:0.

DGAlgebra -- The class of all DGAlgebras
****************************************

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

Some common ways to create DGAlgebras include koszulComplexDGA,
see freeDGAlgebra, setDiff,
and acyclicClosure.

See also
========

  * Basic operations on DG Algebras, --
    Outlines some basic operations on DG Algebras

Functions and methods returning an object of class DGAlgebra:
=============================================================

  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension
  * adjoinVariables -- Extend a DG algebra by a
    user-chosen list of cycles to be killed
  * baseChange -- Transport a DG algebra along a ring map on
    its base
  * ensureDGAlgebraCaches -- Guarantee that the
    standard cache sub-tables are present
  * freeDGAlgebra -- Construct a free DG algebra with
    given generator degrees
  * invalidateDGAlgebraCache -- Discard cached
    derived data so that it is recomputed from scratch
  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree
  * killHomologyAtDegree -- Adjoin variables
    killing the homology of a DG algebra at a prescribed degree
  * koszulComplexDGA -- The Koszul complex on the
    variables of a ring, as a DG algebra
  * minimalModel -- Build the minimal DG algebra
    resolution of a quotient ring
  * restrictDifferential -- Synonym for
    subDGAlgebra, named to match the restricted-differential vocabulary
  * setDiff -- Install or replace the differential on a DG
    algebra
  * subDGAlgebra -- The sub-DG algebra generated by a
    chosen subset of DG generators
  * truncateGenerators -- Restrict a DG algebra to
    its generators of hom-degree strictly above a bound

Methods that use an object of class DGAlgebra:
==============================================

  * "acyclicClosure(DGAlgebra)" -- see acyclicClosure, --
    Tate's construction of a semifree acyclic DG algebra extension
  * "adjoinVariables(DGAlgebra,List)" -- see adjoinVariables,
    -- Extend a DG algebra by a user-chosen list of cycles to
    be killed
  * "baseChange(DGAlgebra,Ring)" -- see baseChange, --
    Transport a DG algebra along a ring map on its base
  * "baseChange(DGAlgebra,RingMap)" -- see baseChange, --
    Transport a DG algebra along a ring map on its base
  * "blockDiff(DGAlgebra,ZZ)" -- see blockDiff, -- prepares a
    map for display
  * DGAlgebra ** DGAlgebra -- Exterior
    tensor product of DG algebras over a common ground ring
  * "tensorFactors(DGAlgebra)" -- see DGAlgebra ** DGAlgebra,
    -- Exterior tensor product of DG algebras over a common
    ground ring
  * "tensorInclusions(DGAlgebra)" -- see DGAlgebra ** DGAlgebra,
    -- Exterior tensor product of DG algebras over
    a common ground ring
  * DGAlgebra ** Ring -- Base change of a DG
    algebra to another ring
  * DGAlgebra / DGIdeal -- Quotient DG algebra by a
    DG ideal
  * "dgAlgebraMap(DGAlgebra,DGAlgebra,Matrix)" -- see dgAlgebraMap,
    -- Define a DG algebra map between DG algebras.
  * "dgAlgebraMultMap(DGAlgebra,RingElement)" -- see dgAlgebraMultMap,
    -- Returns the chain map corresponding to multiplication
    by a cycle.
  * "dgComplex(DGAlgebra)" -- see dgComplex, -- Package a DG
    algebra or DG module as a Complex of free base-ring modules
  * "dgIdeal(DGAlgebra,Ideal)" -- see dgIdeal, -- Construct a DG
    ideal from a list, matrix, or ideal of generators
  * "dgIdeal(DGAlgebra,List)" -- see dgIdeal, -- Construct a DG
    ideal from a list, matrix, or ideal of generators
  * "dgIdeal(DGAlgebra,Matrix)" -- see dgIdeal, -- Construct a
    DG ideal from a list, matrix, or ideal of generators
  * diff(DGAlgebra,RingElement), --
    Apply the differential of a DGAlgebra to a ring element
  * "differential(DGAlgebra)" -- see differential, -- The
    list of generator differentials stored in a DG algebra or DG module
  * "displayBlockDiff(DGAlgebra,Array,Array)" -- see displayBlockDiff,
    -- Shows natural decomposition of a map in the Tate
    resolution
  * "displayBlockDiff(DGAlgebra,List,List)" -- see displayBlockDiff,
    -- Shows natural decomposition of a map in the Tate
    resolution
  * "displayBlockDiff(DGAlgebra,VisibleList)" -- see displayBlockDiff,
    -- Shows natural decomposition of a map in the Tate
    resolution
  * "displayBlockDiff(DGAlgebra,ZZ)" -- see displayBlockDiff,
    -- Shows natural decomposition of a map in the Tate
    resolution
  * "ensureDGAlgebraCaches(DGAlgebra)" -- see ensureDGAlgebraCaches,
    -- Guarantee that the standard cache sub-tables are
    present
  * "findNaryTrivialMasseyOperation(DGAlgebra,List,HashTable,ZZ)" -- see
    findTrivialMasseyOperation, -- Finds a trivial
    Massey operation on a set of generators of H(A)
  * "findTrivialMasseyOperation(DGAlgebra)" -- see
    findTrivialMasseyOperation, -- Finds a trivial
    Massey operation on a set of generators of H(A)
  * "freeDGModule(DGAlgebra,List)" -- see freeDGModule, --
    Construct a free DG module over a DG algebra
  * "generatorDegrees(DGAlgebra)" -- see generatorDegrees,
    -- The hom-degrees (and optional internal degrees) of the
    DG generators
  * generators(DGAlgebra) (missing documentation)
  * "getBasis(ZZ,DGAlgebra)" -- see getBasis, -- Get a basis
    for a particular homological degree of a DG algebra.
  * "getBoundaryPreimage(DGAlgebra,List)" -- see getBoundaryPreimage,
    -- Attempt to find a preimage of a boundary under the
    differential of a DGAlgebra.
  * "getBoundaryPreimage(DGAlgebra,RingElement)" -- see
    getBoundaryPreimage, -- Attempt to find a preimage of
    a boundary under the differential of a DGAlgebra.
  * "getGenerators(DGAlgebra)" -- see getGenerators, --
    Cycles whose classes generate the homology algebra of a DG algebra
  * HH DGAlgebra -- The homology algebra of a DG algebra
  * HH_ZZ DGAlgebra -- Computes the homology of a DG
    algebra as a module
  * "homologyAlgebra(DGAlgebra)" -- see homologyAlgebra,
    -- Compute the homology algebra of a DGAlgebra.
  * "homologyClass(DGAlgebra,RingElement)" -- see homologyClass,
    -- Computes the element of the homology algebra
    corresponding to a cycle in a DGAlgebra.
  * "homologyModule(DGAlgebra,Module)" -- see homologyModule,
    -- Compute the homology of a DGModule as a module over a
    DGAlgebra.
  * "identityDGAlgebraMap(DGAlgebra)" -- see identityDGAlgebraMap,
    -- The identity DGAlgebraMap on a DG algebra
  * "invalidateDGAlgebraCache(DGAlgebra)" -- see
    invalidateDGAlgebraCache, -- Discard cached
    derived data so that it is recomputed from scratch
  * "isAcyclic(DGAlgebra)" -- see isAcyclic, -- Determine
    whether a DG algebra has no higher homology
  * "isDGIdeal(DGAlgebra,Ideal)" -- see isDGIdeal, -- Test
    whether an ideal of A.natural is closed under the differential of A
  * isHomogeneous(DGAlgebra) -- Determine
    if the DGAlgebra respects the gradings of the ring it is defined over.
  * "isHomologyAlgebraTrivial(DGAlgebra)" -- see
    isHomologyAlgebraTrivial, -- Determines if the
    homology algebra of a DGAlgebra is trivial
  * "isValidDGAlgebra(DGAlgebra)" -- see isValidDGAlgebra,
    -- Structural invariant check for a DG algebra
  * isWellDefined(DGAlgebra) -- Check that
    a DG algebra has correct structure and a differential that squares to zero
  * "isWellDefinedDifferential(DGAlgebra)" -- see
    isWellDefinedDifferential, -- Semantic check
    that d^2 = 0 for a DG algebra or DG module
  * "killCycles(DGAlgebra)" -- see killCycles, -- Adjoin
    variables to kill non-bounding cycles in the lowest positive degree
  * "killHomologyAtDegree(DGAlgebra,ZZ)" -- see killHomologyAtDegree,
    -- Adjoin variables killing the homology of a DG
    algebra at a prescribed degree
  * "koszulComplexDGM(DGAlgebra,Module)" -- see koszulComplexDGM,
    -- The Koszul complex of a module as a DG module
  * "liftToDGMap(DGAlgebra,DGAlgebra,RingMap)" -- see liftToDGMap,
    -- Lift a ring homomorphism in degree zero to a DG algebra
    morphism
  * "masseyTripleProduct(DGAlgebra,RingElement,RingElement,RingElement)" -- see
    masseyTripleProduct, -- Computes the Massey
    triple product of a set of cycles or homology classes
  * masseyTripleProduct(DGAlgebra,ZZ,ZZ,ZZ)
    -- Computes the matrix
    representing all triple Massey operations.
  * "maxDegree(DGAlgebra)" -- see maxDegree, -- Computes the
    maximum homological degree of a DGAlgebra
  * "minimalSemifreeResolution(DGAlgebra,Module)" -- see
    minimalSemifreeResolution, -- Build a minimal
    semifree DG module resolution over a DG algebra
  * net(DGAlgebra) -- Short-form display of a DG
    algebra
  * numgens(DGAlgebra) (missing documentation)
  * "polyDifferential(DGAlgebra,RingElement)" -- see polyDifferential,
    -- Matrix and element-level differentials of a DG algebra
  * "polyDifferential(ZZ,DGAlgebra)" -- see polyDifferential,
    -- Matrix and element-level differentials of a DG algebra
  * "polyDiffMonomial(DGAlgebra,RingElement)" -- see polyDiffMonomial,
    -- Leibniz rule on a single monomial of a DG algebra
  * "minimalPresentation(DGAlgebra)" -- see prune(DGAlgebra),
    -- Pruning a DG algebra is the identity
  * prune(DGAlgebra) -- Pruning a DG algebra is
    the identity
  * "restrictDifferential(DGAlgebra,List)" -- see restrictDifferential,
    -- Synonym for subDGAlgebra, named to match the
    restricted-differential vocabulary
  * ring(DGAlgebra) (missing documentation)
  * "semifreeResolution(DGAlgebra,Module)" -- see semifreeResolution,
    -- Build a semifree DG module resolving a module over
    the base ring
  * "setDiff(DGAlgebra,List)" -- see setDiff, -- Install or
    replace the differential on a DG algebra
  * "subDGAlgebra(DGAlgebra,List)" -- see subDGAlgebra, --
    The sub-DG algebra generated by a chosen subset of DG generators
  * "toComplex(DGAlgebra)" -- see toComplex, -- Converts a
    DGAlgebra to a Complex
  * toComplex(DGAlgebra,ZZ) -- Converts a
    DGAlgebra to a Complex
  * "truncateGenerators(DGAlgebra,ZZ)" -- see truncateGenerators,
    -- Restrict a DG algebra to its generators of
    hom-degree strictly above a bound
  * "underlyingAlgebra(DGAlgebra)" -- see underlyingAlgebra,
    -- The graded-commutative algebra carrying the DG
    structure
  * "underlyingRing(DGAlgebra)" -- see underlyingRing, --
    The commutative base ring of a DG algebra or DG module
  * "zerothHomology(DGAlgebra)" -- see zerothHomology, --
    The zeroth homology of a DG algebra as a ring

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:743:0.

dgAlgebra
*********

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

The object dgAlgebra (missing documentation) is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in currentString:1:376.

DGAlgebra ** DGAlgebra -- Exterior tensor product of DG algebras over a common ground ring
******************************************************************************************

  * Operator: ** (Macaulay2Doc),
  * Usage:
        C = A ** B
        (A1, A2) = tensorFactors C
        (iotaA, iotaB) = tensorInclusions C
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * B, an instance of the type DGAlgebra, Must satisfy
        A.ring === B.ring.
  * Outputs:
      * C, an instance of the type DGAlgebra, A DGAlgebra
        over A.ring whose underlying algebra has #A.Degrees + #B.Degrees
        generators, with the obvious multi-degrees, and whose differential is
        d_A on the A-generators and d_B on the B-generators (transported via
        the canonical inclusions).

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

This is the exterior tensor product of A and B as DGAs: both are viewed as
augmented DG algebras over their common ground ring, and the tensor is taken
componentwise in multi-degrees.  Internally the result is cached on A.cache, so
C1 = A ** B and C2 = A ** B return the SAME DGAlgebra object, which is
essential for composition identities to hold downstream.

The helpers tensorFactors, and
tensorInclusions, recover the pair (A, B) and the
canonical inclusions A -> C and B -> C (as DGAlgebraMaps).

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y]                                                             |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o2 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,2                                     |
|      Differential => {x, y}                                                 |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : C = A ** A                                                              |
|                                                                             |
|o3 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,4                                     |
|      Differential => {x, y, x, y}                                           |
|                                                                             |
|o3 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i4 : numgens C.natural                                                       |
|                                                                             |
|o4 = 4                                                                       |
+-----------------------------------------------------------------------------+
|i5 : (iotaA, iotaB) = tensorInclusions C                                     |
|                                                                             |
|o5 = (map (R[T   ..T   ], R[T   ..T   ], {T   , T   , x, y}), map            |
|              1,1   1,4      1,1   1,2     1,1   1,2                         |
|     ------------------------------------------------------------------------|
|     (R[T   ..T   ], R[T   ..T   ], {T   , T   , x, y}))                     |
|         1,1   1,4      1,1   1,2     1,3   1,4                              |
|                                                                             |
|o5 : Sequence                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * DGAlgebraMap ** DGAlgebraMap, --
    Tensor product of DG algebra maps
  * DGModule ** DGModule -- Exterior tensor
    product of DG modules over DG algebras sharing a ground ring

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

  * DGAlgebra ** DGAlgebra -- Exterior
    tensor product of DG algebras over a common ground ring
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:643:0.

DGAlgebraMap -- The class of DG algebra maps
********************************************

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

A DGAlgebraMap represents a morphism of DG algebras. It
carries four pieces of data: a source and target (each a DGAlgebra),
an underlying ring map f.natural on the graded-commutative
algebras, and a degree-zero ring map f.ringMap between the underlying rings. A
DG algebra map is a ring map that commutes with the differentials, so that d_B
\circ f = f \circ d_A where d_A and d_B are the differentials of the source and
target.

There are two principal ways to construct a DG algebra map: dgAlgebraMap,
builds one from a matrix specifying where the DG generators go,
and liftToDGMap, lifts a ring map on the degree-zero part to
a morphism of acyclic closures or Koszul complexes.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c]/ideal{a^3, b^3, c^3}                                  |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : S = R / ideal{a^2*b^2*c^2}                                              |
|                                                                             |
|o2 = S                                                                       |
|                                                                             |
|o2 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i3 : A = acyclicClosure(R, EndDegree => 3)                                   |
|                                                                             |
|o3 = {Ring => R                                        }                     |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   2,3                                     |
|                                 2       2       2                           |
|      Differential => {a, b, c, a T   , b T   , c T   }                      |
|                                   1,1     1,2     1,3                       |
|                                                                             |
|o3 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i4 : B = acyclicClosure(S, EndDegree => 3)                                   |
|                                                                             |
|o4 = {Ring => S                                                              |
|      Underlying algebra => S[T   ..T   , T   ..T   , T   ..T   , T   ..T   ]|
|                               1,1   1,3   2,1   2,4   3,1   3,3   4,1   4,6 |
|                                 2       2       2         2 2       2 2     |
|      Differential => {a, b, c, a T   , b T   , c T   , a*b c T   , b c T   ,|
|                                   1,1     1,2     1,3         1,1       2,1 |
|                                                                             |
|o4 : DGAlgebra                                                               |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|  2 2        2 2       2 2            2 2           2 2            2         |
|-a b T   , -a c T   , b c T   T   , -a c T   T   , b c T   T   , -a T   T   ,|
|      2,3        2,2       1,3 2,1        1,3 2,2       1,2 2,1      1,1 2,4 |
|-----------------------------------------------------------------------------|
|                       }                                                     |
|                                                                             |
|                                                                             |
| 2           2                                                               |
|c T   T   , b T   T   }                                                      |
|   1,3 2,4     1,2 2,4                                                       |
+-----------------------------------------------------------------------------+
|i5 : phi = liftToDGMap(B, A, map(S, R))                                      |
|                                                                             |
|o5 = map (S[T   ..T   , T   ..T   , T   ..T   , T   ..T   ], R[T   ..T   ],  |
|             1,1   1,3   2,1   2,4   3,1   3,3   4,1   4,6      1,1   2,3    |
|                                                                             |
|o5 : DGAlgebraMap                                                            |
|-----------------------------------------------------------------------------|
|{T   , T   , T   , T   , T   , T   , a, b, c})                               |
|  1,1   1,2   1,3   2,1   2,2   2,3                                          |
+-----------------------------------------------------------------------------+
|i6 : source phi === A                                                        |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+
|i7 : target phi === B                                                        |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+

Once constructed, a DG algebra map can be checked with
isWellDefined(DGAlgebraMap), converted to a ComplexMap (Complexes),
via toComplexMap, or pushed through
homology with HH DGAlgebraMap.

See also
========

  * dgAlgebraMap -- Define a DG algebra map between DG
    algebras.
  * liftToDGMap -- Lift a ring homomorphism in degree zero
    to a DG algebra morphism
  * isWellDefined(DGAlgebraMap) -- Define a DG algebra map
    between DG algebras.
  * toComplexMap -- Construct the ComplexMap associated to
    a DGAlgebraMap
  * HH DGAlgebraMap -- The induced ring map on homology
    algebras
  * ringMap -- The degree-zero ring map underlying a
    DGAlgebraMap

Functions and methods returning an object of class DGAlgebraMap:
================================================================

  * dgAlgebraMap -- Define a DG algebra map between DG
    algebras.
  * identityDGAlgebraMap -- The identity
    DGAlgebraMap on a DG algebra
  * liftToDGMap -- Lift a ring homomorphism in degree zero
    to a DG algebra morphism

Methods that use an object of class DGAlgebraMap:
=================================================

  * "isWellDefined(DGAlgebraMap)" -- see dgAlgebraMap, --
    Define a DG algebra map between DG algebras.
  * DGAlgebraMap * DGAlgebraMap, --
    Composition of DG algebra maps
  * DGAlgebraMap ** DGAlgebraMap, --
    Tensor product of DG algebra maps
  * DGAlgebraMap ** Ring -- Base change of a
    DG algebra map along a ring map
  * DGAlgebraMap == DGAlgebraMap (missing documentation)
  * HH DGAlgebraMap -- The induced ring map on homology
    algebras
  * isQuasiIsomorphism(DGAlgebraMap)
    -- Determine whether a DG algebra map
    induces an isomorphism on homology
  * net(DGAlgebraMap) -- Short-form display of a
    DG algebra map
  * "minimalPresentation(DGAlgebraMap)" -- see prune(DGAlgebraMap),
    -- Pruning a DG algebra map is the identity
  * prune(DGAlgebraMap) -- Pruning a DG algebra
    map is the identity
  * source(DGAlgebraMap) -- The source of a DG
    algebra map
  * target(DGAlgebraMap) -- The target of a DG
    algebra map
  * "toComplexMap(DGAlgebraMap)" -- see toComplexMap, --
    Construct the ComplexMap associated to a DGAlgebraMap
  * "toComplexMap(DGAlgebraMap,ZZ)" -- see toComplexMap, --
    Construct the ComplexMap associated to a DGAlgebraMap

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8959:0.

dgAlgebraMap -- Define a DG algebra map between DG algebras.
************************************************************

  * Usage:
        phi = dgAlgebraMap(B,A,M)
  * Inputs:
      * A, an instance of the type DGAlgebra, Source
      * B, an instance of the type DGAlgebra, Target
      * M, a matrix (Macaulay2Doc), A matrix representing where
        the generators of A should be mapped to (akin to ringMap)
  * Outputs:
      * phi, an instance of the type DGAlgebraMap,

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

+--------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c]/ideal{a^3+b^3+c^3,a*b*c}               |
|                                                              |
|o1 = R                                                        |
|                                                              |
|o1 : QuotientRing                                             |
+--------------------------------------------------------------+
|i2 : K1 = koszulComplexDGA(ideal vars R,Variable=>"Y")        |
|                                                              |
|o2 = {Ring => R                          }                    |
|      Underlying algebra => R[Y   ..Y   ]                     |
|                               1,1   1,3                      |
|      Differential => {a, b, c}                               |
|                                                              |
|o2 : DGAlgebra                                                |
+--------------------------------------------------------------+
|i3 : K2 = koszulComplexDGA(ideal {b,c},Variable=>"T")         |
|                                                              |
|o3 = {Ring => R                          }                    |
|      Underlying algebra => R[T   ..T   ]                     |
|                               1,1   1,2                      |
|      Differential => {b, c}                                  |
|                                                              |
|o3 : DGAlgebra                                                |
+--------------------------------------------------------------+
|i4 : g = dgAlgebraMap(K1,K2,matrix{{Y_(1,2),Y_(1,3)}})        |
|                                                              |
|o4 = map (R[Y   ..Y   ], R[T   ..T   ], {Y   , Y   , a, b, c})|
|             1,1   1,3      1,1   1,2     1,2   1,3           |
|                                                              |
|o4 : DGAlgebraMap                                             |
+--------------------------------------------------------------+
|i5 : isWellDefined g                                          |
|                                                              |
|o5 = true                                                     |
+--------------------------------------------------------------+

The function does not check that the DG algebra map is well defined, however.

+-----------------------------------------------------------------+
|i6 : f = dgAlgebraMap(K2,K1,matrix{{0,T_(1,1),T_(1,2)}})         |
|                                                                 |
|o6 = map (R[T   ..T   ], R[Y   ..Y   ], {0, T   , T   , a, b, c})|
|             1,1   1,2      1,1   1,3        1,1   1,2           |
|                                                                 |
|o6 : DGAlgebraMap                                                |
+-----------------------------------------------------------------+
|i7 : isWellDefined f                                             |
|                                                                 |
|o7 = false                                                       |
+-----------------------------------------------------------------+

Ways to use dgAlgebraMap:
=========================

  * "dgAlgebraMap(DGAlgebra,DGAlgebra,Matrix)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9021:0.

DGAlgebraMap * DGAlgebraMap -- Composition of DG algebra maps
*************************************************************

  * Operator: * (Macaulay2Doc),
  * Usage:
        h = g * f
  * Inputs:
      * g, an instance of the type DGAlgebraMap, A map
        with source = target of f.
      * f, an instance of the type DGAlgebraMap,
  * Outputs:
      * h, an instance of the type DGAlgebraMap, The
        composite DGAlgebraMap whose underlying RingMap is g.natural *
        f.natural.

See also
========

  * identityDGAlgebraMap -- The identity
    DGAlgebraMap on a DG algebra
  * dgAlgebraMap -- Define a DG algebra map between DG
    algebras.

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

  * DGAlgebraMap * DGAlgebraMap, --
    Composition of DG algebra maps
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:599:0.

DGAlgebraMap ** DGAlgebraMap -- Tensor product of DG algebra maps
*****************************************************************

  * Operator: ** (Macaulay2Doc),
  * Usage:
        h = f ** g
  * Inputs:
      * f, an instance of the type DGAlgebraMap, A:A -> A'
      * g, an instance of the type DGAlgebraMap, B:B -> B'
  * Outputs:
      * h, an instance of the type DGAlgebraMap, The map A
        ** B -> A' ** B' that restricts to f on the A-generators and g on the
        B-generators, transported via the canonical inclusions.

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

Functorial with the DGA tensor product: identityDGAlgebraMap(A) **
identityDGAlgebraMap(B) equals identityDGAlgebraMap(A ** B).

See also
========

  * DGAlgebra ** DGAlgebra -- Exterior
    tensor product of DG algebras over a common ground ring
  * identityDGAlgebraMap -- The identity
    DGAlgebraMap on a DG algebra

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

  * DGAlgebraMap ** DGAlgebraMap, --
    Tensor product of DG algebra maps
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:668:0.

dgAlgebraMultMap -- Returns the chain map corresponding to multiplication by a cycle.
*************************************************************************************

  * Usage:
        phi = dgAlgebraMultMap(A,z)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * z, a ring element (Macaulay2Doc),
  * Outputs:
      * phi, a map of complexes (Complexes),

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

If A is a DGAlgebra, and z is a cycle of A, then left multiplication of A by z
gives a chain map from A to A.  This command converts A to a complex using
toComplex, and constructs a ComplexMap (Complexes),
that represents left multiplication by z. This command
is used to determine the module structure that is computed in
homologyModule.

+------------------------------------------+
|i1 : R = QQ[x,y,z]/ideal{x^3,y^3,z^3}     |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : QuotientRing                         |
+------------------------------------------+
|i2 : KR = koszulComplexDGA R              |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,3  |
|      Differential => {x, y, z}           |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : z1 = x^2*T_(1,1)                     |
|                                          |
|      2                                   |
|o3 = x T                                  |
|        1,1                               |
|                                          |
|o3 : R[T   ..T   ]                        |
|        1,1   1,3                         |
+------------------------------------------+
|i4 : phi = dgAlgebraMultMap(KR,z1)        |
|                                          |
|          3                  1            |
|o4 = 1 : R  <-------------- R  : 0        |
|               {1} | x2 |                 |
|               {1} | 0  |                 |
|               {1} | 0  |                 |
|                                          |
|          3                       3       |
|     2 : R  <------------------- R  : 1   |
|               {2} | 0 x2 0  |            |
|               {2} | 0 0  x2 |            |
|               {2} | 0 0  0  |            |
|                                          |
|          1                      3        |
|     3 : R  <------------------ R  : 2    |
|               {3} | 0 0 x2 |             |
|                                          |
|o4 : ComplexMap                           |
+------------------------------------------+

As you can see, the degree of phi is the homological degree of z:

+---------------------------------+
|i5 : degree phi == first degree z|
|                                 |
|o5 = true                        |
+---------------------------------+

Care is also taken to ensure the resulting map is homogeneous if R and z are:

+----------------------+
|i6 : isHomogeneous phi|
|                      |
|o6 = true             |
+----------------------+

One may then view the action of multiplication by the homology class of z upon
taking the induced map in homology:

+-------------------------------------------------+
|i7 : Hphi = prune HH(phi); (Hphi_0,Hphi_1,Hphi_2)|
|                                                 |
|o8 = (0, {6} | 0 1 0 |, {9} | 0 0 1 |)           |
|         {6} | 0 0 1 |                           |
|         {6} | 0 0 0 |                           |
|                                                 |
|o8 : Sequence                                    |
+-------------------------------------------------+

Ways to use dgAlgebraMultMap:
=============================

  * "dgAlgebraMultMap(DGAlgebra,RingElement)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9174:0.

DGModule ** DGModule -- Exterior tensor product of DG modules over DG algebras sharing a ground ring
****************************************************************************************************

  * Operator: ** (Macaulay2Doc),
  * Usage:
        P = M ** N
  * Inputs:
      * M, an instance of the type DGModule, A (free) DG
        module over some DG algebra A.
      * N, an instance of the type DGModule, A (free) DG
        module over some DG algebra B, with A.ring === B.ring.
  * Outputs:
      * P, an instance of the type DGModule, A (free) DG
        module over A ** B whose natural generators are indexed
        lexicographically by (i, j) with i ranging over M-generators and j over
        N-generators.  The multi-degree of (i, j) is M.Degrees#i + N.Degrees#j
        coordinate-wise, and the differential is $d(e_i \otimes f_j) = d_M(e_i)
        \otimes f_j + (-1)^{|e_i|}\, e_i \otimes d_N(f_j)$.

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

This is the EXTERIOR tensor product: we do not quotient by an A- or B-action.
The resulting DGModule lives over A ** B via the canonical inclusions. The
result is cached on M.cache, so M ** N returns the same object on repeat.

+------------------------------------------------------------+
|i1 : R = ZZ/101[x,y]                                        |
|                                                            |
|o1 = R                                                      |
|                                                            |
|o1 : PolynomialRing                                         |
+------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                 |
|                                                            |
|o2 = {Ring => R                          }                  |
|      Underlying algebra => R[T   ..T   ]                   |
|                               1,1   1,2                    |
|      Differential => {x, y}                                |
|                                                            |
|o2 : DGAlgebra                                              |
+------------------------------------------------------------+
|i3 : M = freeDGModule(A, {0, 1})                            |
|                                                            |
|o3 = {Base ring => R                       }                |
|      DG algebra => R[T   ..T   ]                           |
|                       1,1   1,2                            |
|                                       2                    |
|      Natural module => (R[T   ..T   ])                     |
|                            1,1   1,2                       |
|      Generator degrees => {{0, 0}, {1, 0}}                 |
|      Differentials on gens => {0, 0}                       |
|                                                            |
|o3 : DGModule                                               |
+------------------------------------------------------------+
|i4 : ng = apply(rank M.natural, i -> (M.natural)_i)         |
|                                                            |
|o4 = {| 1 |, | 0 |}                                         |
|      | 0 |  | 1 |                                          |
|                                                            |
|o4 : List                                                   |
+------------------------------------------------------------+
|i5 : setDiff(M, {0, x * ng#0})                              |
|                                                            |
|o5 = {Base ring => R                       }                |
|      DG algebra => R[T   ..T   ]                           |
|                       1,1   1,2                            |
|                                       2                    |
|      Natural module => (R[T   ..T   ])                     |
|                            1,1   1,2                       |
|      Generator degrees => {{0, 0}, {1, 0}}                 |
|      Differentials on gens => {0, | x |}                   |
|                                   | 0 |                    |
|                                                            |
|o5 : DGModule                                               |
+------------------------------------------------------------+
|i6 : P = M ** M                                             |
|                                                            |
|o6 = {Base ring => R                                       }|
|      DG algebra => R[T   ..T   ]                           |
|                       1,1   1,4                            |
|                                       4                    |
|      Natural module => (R[T   ..T   ])                     |
|                            1,1   1,4                       |
|      Generator degrees => {{0, 0}, {1, 0}, {1, 0}, {2, 0}} |
|      Differentials on gens => {0, | x |, | x |, |  0 |}    |
|                                   | 0 |  | 0 |  |  x |     |
|                                   | 0 |  | 0 |  | -x |     |
|                                   | 0 |  | 0 |  |  0 |     |
|                                                            |
|o6 : DGModule                                               |
+------------------------------------------------------------+
|i7 : P.dgAlgebra === (A ** A)                               |
|                                                            |
|o7 = true                                                   |
+------------------------------------------------------------+

See also
========

  * DGAlgebra ** DGAlgebra -- Exterior
    tensor product of DG algebras over a common ground ring
  * DGModuleMap ** DGModuleMap -- Tensor
    product of DG module maps
  * freeDGModule -- Construct a free DG module over a DG
    algebra

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

  * DGModule ** DGModule -- Exterior tensor
    product of DG modules over DG algebras sharing a ground ring
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:706:0.

DGModuleMap -- The class of morphisms of DG modules over a common DG algebra
****************************************************************************

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

A DGModuleMap encodes an A-linear chain map between two DGModules sharing the
same underlying DG algebra A.  Create one via dgModuleMap.
See Basic operations on DG Module Maps,
for a guided tour.

See also
========

  * DGModule -- The class of DG modules over a DG algebra
  * dgModuleMap -- Construct a DGModuleMap from a matrix or
    from a list of image Vectors
  * Basic operations on DG Module Maps
    -- Outlines some basic operations on DGModuleMaps

Functions and methods returning an object of class DGModuleMap:
===============================================================

  * dgModuleMap -- Construct a DGModuleMap from a matrix or
    from a list of image Vectors
  * identityDGModuleMap -- The identity DGModuleMap
    on a DG module
  * liftToDGModuleMap -- Lift an image of
    hom-degree-0 generators to a full DGModuleMap
  * zeroDGModuleMap -- The zero DGModuleMap between two
    DG modules over a common algebra

Methods that use an object of class DGModuleMap:
================================================

  * - DGModuleMap (missing documentation)
  * cokernel(DGModuleMap) -- Cokernel of a DG
    module map as a DG quotient module of its target
  * degree(DGModuleMap) (missing documentation)
  * DGModuleMap * DGModuleMap (missing documentation)
  * DGModuleMap * Number (missing documentation)
  * DGModuleMap * QQ (missing documentation)
  * DGModuleMap * RingElement (missing documentation)
  * DGModuleMap * ZZ (missing documentation)
  * DGModuleMap ** DGModuleMap -- Tensor
    product of DG module maps
  * DGModuleMap ** Ring -- Base change of a DG
    module map along a ring map
  * DGModuleMap + DGModuleMap (missing documentation)
  * DGModuleMap - DGModuleMap (missing documentation)
  * DGModuleMap == DGModuleMap -- Elementary
    predicates and constructors for DGModuleMaps
  * "isHomogeneous(DGModuleMap)" -- see DGModuleMap == DGModuleMap,
    -- Elementary predicates and constructors for
    DGModuleMaps
  * "isQuasiIsomorphism(DGModuleMap)" -- see DGModuleMap == DGModuleMap,
    -- Elementary predicates and constructors for
    DGModuleMaps
  * DGModuleMap == ZZ (missing documentation)
  * DGModuleMap Vector (missing documentation)
  * HH DGModuleMap -- The induced map on graded homology
    modules over HH(A)
  * homology(DGModuleMap,ZZ) -- The
    induced map on degree-n homology of a DG module map
  * image(DGModuleMap) -- Image of a DG module
    map as a DG submodule of its target
  * isInjective(DGModuleMap) (missing documentation)
  * isIsomorphism(DGModuleMap) (missing documentation)
  * isSurjective(DGModuleMap) (missing documentation)
  * isWellDefined(DGModuleMap) -- Check
    that a DG module map has correct structure and is a chain map
  * kernel(DGModuleMap) -- Kernel of a DG
    module map as a DG submodule of its source
  * net(DGModuleMap) (missing documentation)
  * Number * DGModuleMap (missing documentation)
  * "minimalPresentation(DGModuleMap)" -- see prune(DGModuleMap),
    -- Pruning a DG module map is the identity
  * prune(DGModuleMap) -- Pruning a DG module
    map is the identity
  * QQ * DGModuleMap (missing documentation)
  * ring(DGModuleMap) (missing documentation)
  * RingElement * DGModuleMap (missing documentation)
  * source(DGModuleMap) (missing documentation)
  * target(DGModuleMap) (missing documentation)
  * toComplexMap(DGModuleMap) -- Export a
    DG module map to a ComplexMap
  * toComplexMap(DGModuleMap,ZZ), --
    The per-hom-degree component of a DG module map as a matrix
  * ZZ * DGModuleMap (missing documentation)
  * ZZ == DGModuleMap (missing documentation)

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:288:0.

dgModuleMap -- Construct a DGModuleMap from a matrix or from a list of image Vectors
************************************************************************************

  * Usage:
        f = dgModuleMap(N, M, img)
  * Inputs:
      * N, an instance of the type DGModule, The target
        DGModule.
      * M, an instance of the type DGModule, The source
        DGModule; must share the same DG algebra as N.
      * img, Either a Matrix whose i-th column encodes the image of the i-th
        natural generator of M in N.natural, or a List of Vectors of the same
        length as M.Degrees (one Vector per source generator).
  * Outputs:
      * f, an instance of the type DGModuleMap,

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

The map f satisfies the A-linearity constraint by construction: the image of a
general element \sum a_i e_i is \sum a_i f(e_i), where f(e_i) is the i-th entry
supplied.  Whether f is also a chain map (i.e.\ commutes with the
differentials) can be verified with isWellDefined (Macaulay2Doc).

A particularly useful application is to build multiplication-by-a-ring-element
chain maps on a minimal semifree resolution, whose induced action on homology
recovers the action of the element on Tor.  Over the complete intersection R =
k[x, y]/(x^2, y^2), the variable y acts as zero on the residue field, and
indeed the induced map on homology of the multiplication-by-y chain map is zero
in every degree:

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y] / ideal(x^2, y^2)                                          |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o2 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,2                                     |
|      Differential => {x, y}                                                 |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : Mdg = minimalSemifreeResolution(A, R^1 / ideal(x, y), EndDegree => 3)   |
|                                                                             |
|o3 = {Base ring => R                                                         |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       6                                     |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}, {4, 4}, {4, 4}, {4, 4}}  |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |, |     0    |, |
|                                   |     0    |  |     0    |  | xT_(1,1) |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                   |     0    |  |     0    |  |     0    |  |
|                                                                             |
|o3 : DGModule                                                                |
|-----------------------------------------------------------------------------|
|                           }                                                 |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
||     0    |, |     0    |}                                                  |
|| yT_(1,2) |  |     0    |                                                   |
|| xT_(1,1) |  | yT_(1,2) |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
+-----------------------------------------------------------------------------+
|i4 : natGens = apply(rank Mdg.natural, i -> (Mdg.natural)_i)                 |
|                                                                             |
|o4 = {| 1 |, | 0 |, | 0 |, | 0 |, | 0 |, | 0 |}                              |
|      | 0 |  | 1 |  | 0 |  | 0 |  | 0 |  | 0 |                               |
|      | 0 |  | 0 |  | 1 |  | 0 |  | 0 |  | 0 |                               |
|      | 0 |  | 0 |  | 0 |  | 1 |  | 0 |  | 0 |                               |
|      | 0 |  | 0 |  | 0 |  | 0 |  | 1 |  | 0 |                               |
|      | 0 |  | 0 |  | 0 |  | 0 |  | 0 |  | 1 |                               |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : fy = dgModuleMap(Mdg, Mdg, apply(natGens, g -> y * g))                  |
|                                                                             |
|                               6                                             |
|o5 = {Source => (R[T   ..T   ])        }                                     |
|                    1,1   1,2                                                |
|                               6                                             |
|      Target => (R[T   ..T   ])                                              |
|                    1,1   1,2                                                |
|      Natural => {0, 0} | y 0 0 0 0 0 |                                      |
|                 {2, 2} | 0 y 0 0 0 0 |                                      |
|                 {2, 2} | 0 0 y 0 0 0 |                                      |
|                 {4, 4} | 0 0 0 y 0 0 |                                      |
|                 {4, 4} | 0 0 0 0 y 0 |                                      |
|                 {4, 4} | 0 0 0 0 0 y |                                      |
|                                                                             |
|o5 : DGModuleMap                                                             |
+-----------------------------------------------------------------------------+
|i6 : isWellDefined fy                                                        |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+
|i7 : cmy = toComplexMap fy                                                   |
|                                                                             |
|          1             1                                                    |
|o7 = 0 : R  <--------- R  : 0                                                |
|               | y |                                                         |
|                                                                             |
|          2                   2                                              |
|     1 : R  <--------------- R  : 1                                          |
|               {1} | y 0 |                                                   |
|               {1} | 0 y |                                                   |
|                                                                             |
|          3                     3                                            |
|     2 : R  <----------------- R  : 2                                        |
|               {2} | y 0 0 |                                                 |
|               {2} | 0 y 0 |                                                 |
|               {2} | 0 0 y |                                                 |
|                                                                             |
|          4                       4                                          |
|     3 : R  <------------------- R  : 3                                      |
|               {3} | y 0 0 0 |                                               |
|               {3} | 0 y 0 0 |                                               |
|               {3} | 0 0 y 0 |                                               |
|               {3} | 0 0 0 y |                                               |
|                                                                             |
|          5                         5                                        |
|     4 : R  <--------------------- R  : 4                                    |
|               {4} | y 0 0 0 0 |                                             |
|               {4} | 0 y 0 0 0 |                                             |
|               {4} | 0 0 y 0 0 |                                             |
|               {4} | 0 0 0 y 0 |                                             |
|               {4} | 0 0 0 0 y |                                             |
|                                                                             |
|          6                           6                                      |
|     5 : R  <----------------------- R  : 5                                  |
|               {5} | y 0 0 0 0 0 |                                           |
|               {5} | 0 y 0 0 0 0 |                                           |
|               {5} | 0 0 y 0 0 0 |                                           |
|               {5} | 0 0 0 y 0 0 |                                           |
|               {5} | 0 0 0 0 y 0 |                                           |
|               {5} | 0 0 0 0 0 y |                                           |
|                                                                             |
|          3                     3                                            |
|     6 : R  <----------------- R  : 6                                        |
|               {6} | y 0 0 |                                                 |
|               {6} | 0 y 0 |                                                 |
|               {6} | 0 0 y |                                                 |
|                                                                             |
|o7 : ComplexMap                                                              |
+-----------------------------------------------------------------------------+
|i8 : apply(0..3, n -> prune HH_n cmy)                                        |
|                                                                             |
|o8 = (0, 0, 0, 0)                                                            |
|                                                                             |
|o8 : Sequence                                                                |
+-----------------------------------------------------------------------------+

The same constructor also accepts a Matrix (Macaulay2Doc), whose
columns give the images of the natural generators.  For instance, supplying the
identity matrix of Mdg.natural reproduces the identity chain map:

+-------------------------------------------------+
|i9 : idmat = id_(Mdg.natural)                    |
|                                                 |
|o9 = {0, 0} | 1 0 0 0 0 0 |                      |
|     {2, 2} | 0 1 0 0 0 0 |                      |
|     {2, 2} | 0 0 1 0 0 0 |                      |
|     {4, 4} | 0 0 0 1 0 0 |                      |
|     {4, 4} | 0 0 0 0 1 0 |                      |
|     {4, 4} | 0 0 0 0 0 1 |                      |
|                                                 |
|                           6                    6|
|o9 : Matrix (R[T   ..T   ])  <-- (R[T   ..T   ]) |
|                1,1   1,2            1,1   1,2   |
+-------------------------------------------------+
|i10 : g = dgModuleMap(Mdg, Mdg, idmat)           |
|                                                 |
|                                6                |
|o10 = {Source => (R[T   ..T   ])        }        |
|                     1,1   1,2                   |
|                                6                |
|       Target => (R[T   ..T   ])                 |
|                     1,1   1,2                   |
|       Natural => {0, 0} | 1 0 0 0 0 0 |         |
|                  {2, 2} | 0 1 0 0 0 0 |         |
|                  {2, 2} | 0 0 1 0 0 0 |         |
|                  {4, 4} | 0 0 0 1 0 0 |         |
|                  {4, 4} | 0 0 0 0 1 0 |         |
|                  {4, 4} | 0 0 0 0 0 1 |         |
|                                                 |
|o10 : DGModuleMap                                |
+-------------------------------------------------+
|i11 : isWellDefined g                            |
|                                                 |
|o11 = true                                       |
+-------------------------------------------------+
|i12 : g == identityDGModuleMap Mdg               |
|                                                 |
|o12 = true                                       |
+-------------------------------------------------+

See also
========

  * identityDGModuleMap -- The identity DGModuleMap
    on a DG module
  * zeroDGModuleMap -- The zero DGModuleMap between two
    DG modules over a common algebra
  * liftToDGModuleMap -- Lift an image of
    hom-degree-0 generators to a full DGModuleMap
  * isWellDefined(DGModuleMap) -- Check
    that a DG module map has correct structure and is a chain map
  * Basic operations on DG Module Maps
    -- Outlines some basic operations on DGModuleMaps

Ways to use dgModuleMap:
========================

  * "dgModuleMap(DGModule,DGModule,List)"
  * "dgModuleMap(DGModule,DGModule,Matrix)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:350:0.

DGModuleMap ** DGModuleMap -- Tensor product of DG module maps
**************************************************************

  * Operator: ** (Macaulay2Doc),
  * Usage:
        h = F ** G
  * Inputs:
      * F, an instance of the type DGModuleMap, M -> M'
      * G, an instance of the type DGModuleMap, N -> N'
  * Outputs:
      * h, an instance of the type DGModuleMap, The map M
        ** N -> M' ** N' acting by F on the first factor and G on the second
        factor.

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

Functorial: idM ** idN equals identityDGModuleMap(M ** N), and tensor with a
zero map is a zero map.

See also
========

  * DGModule ** DGModule -- Exterior tensor
    product of DG modules over DG algebras sharing a ground ring
  * identityDGModuleMap -- The identity DGModuleMap
    on a DG module
  * zeroDGModuleMap -- The zero DGModuleMap between two
    DG modules over a common algebra

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

  * DGModuleMap ** DGModuleMap -- Tensor
    product of DG module maps
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:731:0.

DGModuleMap == DGModuleMap -- Elementary predicates and constructors for DGModuleMaps
*************************************************************************************

  * Operator: == (Macaulay2Doc),

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

Auxiliary operations mirroring those on ComplexMap. For maps f, g between DG
modules over a common DG algebra:

f == g -- equality of source, target, and underlying natural matrix.

isHomogeneous f -- agrees with isHomogeneous f.natural.

map(N, M, 0) -- returns the zero map M -> N. map(M, M, 1) -- returns the
identity on M.

isQuasiIsomorphism f -- returns true iff the induced chain map on
toComplexMap, is a quasi-isomorphism.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y]/ideal(x^2, y^2)                                             |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : Mdg = minimalSemifreeResolution(koszulComplexDGA R, R^1 / ideal(x,y),   |
|                                                                             |
|o2 = {Base ring => R                                          }              |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       3                                     |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}}                          |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |}               |
|                                   |     0    |  |     0    |                |
|                                   |     0    |  |     0    |                |
|                                                                             |
|o2 : DGModule                                                                |
|-----------------------------------------------------------------------------|
|EndDegree => 2)                                                              |
+-----------------------------------------------------------------------------+
|i3 : idM = identityDGModuleMap Mdg                                           |
|                                                                             |
|                               3                                             |
|o3 = {Source => (R[T   ..T   ])  }                                           |
|                    1,1   1,2                                                |
|                               3                                             |
|      Target => (R[T   ..T   ])                                              |
|                    1,1   1,2                                                |
|      Natural => {0, 0} | 1 0 0 |                                            |
|                 {2, 2} | 0 1 0 |                                            |
|                 {2, 2} | 0 0 1 |                                            |
|                                                                             |
|o3 : DGModuleMap                                                             |
+-----------------------------------------------------------------------------+
|i4 : zM = zeroDGModuleMap(Mdg, Mdg)                                          |
|                                                                             |
|                               3                                             |
|o4 = {Source => (R[T   ..T   ]) }                                            |
|                    1,1   1,2                                                |
|                               3                                             |
|      Target => (R[T   ..T   ])                                              |
|                    1,1   1,2                                                |
|      Natural => 0                                                           |
|                                                                             |
|o4 : DGModuleMap                                                             |
+-----------------------------------------------------------------------------+
|i5 : idM == idM                                                              |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+
|i6 : map(Mdg, Mdg, 0) == zM                                                  |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+
|i7 : map(Mdg, Mdg, 1) == idM                                                 |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+
|i8 : isQuasiIsomorphism idM                                                  |
|                                                                             |
|o8 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * DGModuleMap -- The class of morphisms of DG modules
    over a common DG algebra
  * identityDGModuleMap -- The identity DGModuleMap
    on a DG module
  * zeroDGModuleMap -- The zero DGModuleMap between two
    DG modules over a common algebra
  * Basic operations on DG Module Maps
    -- Outlines some basic operations on DGModuleMaps

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

  * DGModuleMap == DGModuleMap -- Elementary
    predicates and constructors for DGModuleMaps
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:553:0.

diff(DGAlgebra,RingElement) -- Apply the differential of a DGAlgebra to a ring element
**************************************************************************************

  * Function: diff (Macaulay2Doc),
  * Usage:
        b = diff(A, a)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * a, a ring element (Macaulay2Doc), an element of
        A.natural
  * Outputs:
      * b, a ring element (Macaulay2Doc), the image d_A(a)

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

Returns the image of a under the differential of A. The element a must be a
ring element of the underlying graded-commutative algebra A.natural; products,
sums, and polynomial expressions in the DG generators are all valid inputs.
The differential is applied by the Leibniz rule, so homogeneous components are
processed independently.

+--------------------------------------------------+
|i1 : R = ZZ/101[x,y,z]                            |
|                                                  |
|o1 = R                                            |
|                                                  |
|o1 : PolynomialRing                               |
+--------------------------------------------------+
|i2 : A = koszulComplexDGA R                       |
|                                                  |
|o2 = {Ring => R                          }        |
|      Underlying algebra => R[T   ..T   ]         |
|                               1,1   1,3          |
|      Differential => {x, y, z}                   |
|                                                  |
|o2 : DGAlgebra                                    |
+--------------------------------------------------+
|i3 : diff(A, T_(1,1) * T_(1,2))                   |
|                                                  |
|o3 = - y*T    + x*T                               |
|          1,1      1,2                            |
|                                                  |
|o3 : R[T   ..T   ]                                |
|        1,1   1,3                                 |
+--------------------------------------------------+
|i4 : diff(A, diff(A, T_(1,1) * T_(1,2) * T_(1,3)))|
|                                                  |
|o4 = 0                                            |
|                                                  |
|o4 : R[T   ..T   ]                                |
|        1,1   1,3                                 |
+--------------------------------------------------+

When a is a cycle, the result is zero:

+------------------------------+
|i5 : z = x*T_(1,2) - y*T_(1,1)|
|                              |
|o5 = - y*T    + x*T           |
|          1,1      1,2        |
|                              |
|o5 : R[T   ..T   ]            |
|        1,1   1,3             |
+------------------------------+
|i6 : diff(A, z)               |
|                              |
|o6 = 0                        |
|                              |
|o6 : R[T   ..T   ]            |
|        1,1   1,3             |
+------------------------------+

To solve the equation diff(A, b) == z for a boundary z, use
getBoundaryPreimage.

See also
========

  * DGAlgebra -- The class of all DGAlgebras
  * getBoundaryPreimage -- Attempt to find a
    preimage of a boundary under the differential of a DGAlgebra.
  * homologyClass -- Computes the element of the homology
    algebra corresponding to a cycle in a DGAlgebra.

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

  * diff(DGAlgebra,RingElement), --
    Apply the differential of a DGAlgebra to a ring element
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8767:0.

EndDegree -- Option to specify the last homological degree processed by an iterative DG construction
****************************************************************************************************

  * Usage:
        acyclicClosure(..., EndDegree => n)
        killCycles(..., EndDegree => n)
        isAcyclic(..., EndDegree => n)
        toComplexMap(..., EndDegree => n)

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

Bounds how far an iterative DG algebra computation should proceed.  In
acyclicClosure, this limits the homological degree of new
generators adjoined; in isAcyclic, it is the highest degree in
which homology is checked; in toComplexMap, it governs how
many homological degrees of the resulting chain map are computed.

The default value varies by function and is documented on each specific
bracketed option node.  This option is required whenever a DG algebra has
generators in even homological degree, since the algebra is otherwise
unbounded.

See also
========

  * StartDegree -- Option to specify the first homological
    degree processed by an iterative DG construction
  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension
  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree
  * isAcyclic -- Determine whether a DG algebra has no higher
    homology
  * toComplexMap -- Construct the ComplexMap associated to
    a DGAlgebraMap

Functions with optional argument named EndDegree:
=================================================

  * acyclicClosure(...,EndDegree=>...)
    -- Option to specify
    the degree to stop computing the acyclic closure
  * isAcyclic(...,EndDegree=>...)
    -- Option to specify the
    degree to finish checking acyclicity
  * killCycles(...,EndDegree=>...)
    -- Last homological
    degree processed by killCycles
  * "liftToDGMap(...,EndDegree=>...)" -- see liftToDGMap, --
    Lift a ring homomorphism in degree zero to a DG algebra morphism
  * "liftToDGModuleMap(...,EndDegree=>...)" -- see liftToDGModuleMap,
    -- Lift an image of hom-degree-0 generators to a full
    DGModuleMap
  * "minimalModel(...,EndDegree=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * minimalSemifreeResolution(...,EndDegree=>...)
    -- Option
    to specify the last degree at which minimalSemifreeResolution kills cycles
  * semifreeResolution(...,EndDegree=>...)
    -- Option to
    specify the last degree at which semifreeResolution kills cycles
  * "toComplexMap(...,EndDegree=>...)" -- see toComplexMap,
    -- Construct the ComplexMap associated to a DGAlgebraMap

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

The object EndDegree, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9355:0.

expandGeomSeries -- Expand a geometric series to a specified degree.
********************************************************************

  * Usage:
        pSeries = expandGeomSeries(f,n)
  * Inputs:
      * f, a ring element (Macaulay2Doc), Ratio of the
        geometric series to be expanded.
      * n, an integer (Macaulay2Doc), Degree which to expand the
        geometric series.
  * Outputs:
      * pSeries, a ring element (Macaulay2Doc), Power series
        representation of the geometric series.

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

If the user supplies a list instead of a RingElement as the first argument, the
return value is the product of all the each of the geometric series expanded to
degree n obtained by calling expandGeomSeries on each element of the list.

+-----------------------------------------------------------------------------+
|i1 : A = ZZ[S,T_0,T_1]                                                       |
|                                                                             |
|o1 = A                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : f = expandGeomSeries(S^2*T_0^8,10)                                      |
|                                                                             |
|      10 40    8 32    6 24    4 16    2 8                                   |
|o2 = S  T   + S T   + S T   + S T   + S T  + 1                               |
|         0       0       0       0       0                                   |
|                                                                             |
|o2 : A                                                                       |
+-----------------------------------------------------------------------------+
|i3 : g = expandGeomSeries(S^4*T_1^15,10)                                     |
|                                                                             |
|      8 30    4 15                                                           |
|o3 = S T   + S T   + 1                                                       |
|        1       1                                                            |
|                                                                             |
|o3 : A                                                                       |
+-----------------------------------------------------------------------------+
|i4 : h = expandGeomSeries({S^2*T_0^8,S^4*T_1^15},10)                         |
|                                                                             |
|      10 40    10 24 15    10 8 30    8 32    8 16 15    8 30    6 24        |
|o4 = S  T   + S  T  T   + S  T T   + S T   + S T  T   + S T   + S T   +      |
|         0        0  1        0 1       0       0  1       1       0         |
|     ------------------------------------------------------------------------|
|      6 8 15    4 16    4 15    2 8                                          |
|     S T T   + S T   + S T   + S T  + 1                                      |
|        0 1       0       1       0                                          |
|                                                                             |
|o4 : A                                                                       |
+-----------------------------------------------------------------------------+
|i5 : B = A/(first gens A)^11                                                 |
|                                                                             |
|o5 = B                                                                       |
|                                                                             |
|o5 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i6 : substitute(f*g,B) == h                                                  |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

Ways to use expandGeomSeries:
=============================

  * "expandGeomSeries(List,ZZ)"
  * "expandGeomSeries(RingElement,ZZ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8694:0.

findTrivialMasseyOperation -- Finds a trivial Massey operation on a set of generators of H(A)
*********************************************************************************************

  * Usage:
        tmo = findTrivialMasseyOperation(A)
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Optional inputs (Macaulay2Doc),:
      * GenDegreeLimit,
        => ..., default value infinity, Maximum
        homological degree of generators used in the trivial Massey operation
        search
      * TMOLimit,
        => ..., default value infinity, Maximum arity of Massey
        products searched for bounding
  * Outputs:
      * seq, a sequence (Macaulay2Doc), A sequence seq whose
        first entry reports whether a trivial Massey operation has been found,
        and the second entry is a hash table with keys given by monomials in a
        generating set of the positive degree homology of A and values the
        element that bounds the Massey product corresponding to that monomial.

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

This function the element that bounds all potentially nonzero Massey products
(before taking homology class). The maximum degree of a generating cycle is
specified in the option GenDegreeLimit, if needed.

Golod rings are defined by being those rings whose Koszul complex K^R has a
trivial Massey operation. Also, the existence of a trivial Massey operation on
a DG algebra A forces the multiplication on H(A) to be trivial.  An example of
a ring R such that H(K^R) has trivial multiplication, yet K^R does not admit a
trivial Massey operation is unknown.  Such an example cannot be monomially
defined, by a result of Jollenbeck and Berglund.

This is an example of a Golod ring.  It is Golod since it is the
Stanley-Reisner ideal of a flag complex whose 1-skeleton is chordal
[Jollenbeck-Berglund].

+-----------------------------------------------------------------------------+
|i1 : Q = ZZ/101[x_1..x_6]                                                    |
|                                                                             |
|o1 = Q                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal (x_3*x_5,x_4*x_5,x_1*x_6,x_3*x_6,x_4*x_6)                     |
|                                                                             |
|o2 = ideal (x x , x x , x x , x x , x x )                                    |
|             3 5   4 5   1 6   3 6   4 6                                     |
|                                                                             |
|o2 : Ideal of Q                                                              |
+-----------------------------------------------------------------------------+
|i3 : R = Q/I                                                                 |
|                                                                             |
|o3 = R                                                                       |
|                                                                             |
|o3 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i4 : A = koszulComplexDGA(R)                                                 |
|                                                                             |
|o4 = {Ring => R                               }                              |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,6                                     |
|      Differential => {x , x , x , x , x , x }                               |
|                        1   2   3   4   5   6                                |
|                                                                             |
|o4 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i5 : isHomologyAlgebraTrivial(A,GenDegreeLimit=>3)                           |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+
|i6 : cycleList = getGenerators(A)                                            |
|                                                                             |
|o6 = {x T   , x T   , x T   , x T   , x T   , -x T   T   , -x T   T   ,      |
|       5 1,4   5 1,3   6 1,4   6 1,3   6 1,1    5 1,3 1,4    6 1,1 1,3       |
|     ------------------------------------------------------------------------|
|     -x T   T   , -x T   T   , - x T   T    + x T   T   , - x T   T    +     |
|       6 1,3 1,4    6 1,1 1,4     6 1,4 1,5    5 1,4 1,6     6 1,3 1,5       |
|     ------------------------------------------------------------------------|
|     x T   T   , x T   T   T   , x T   T   T    - x T   T   T   }            |
|      5 1,3 1,6   6 1,1 1,3 1,4   6 1,3 1,4 1,5    5 1,3 1,4 1,6             |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : (hasTMO, tmoSoFar) = findTrivialMasseyOperation(A)                      |
|                                                                             |
|o7 = (true, HashTable{{0, 1} => -x T   T   T                 })              |
|                                  5 1,3 1,4 1,5                              |
|                      {0, 3, 4} => x T   T   T   T   T                       |
|                                    6 1,1 1,3 1,4 1,5 1,6                    |
|                      {0, 3} => -x T   T   T                                 |
|                                  6 1,3 1,4 1,5                              |
|                      {0, 4, 3} => -x T   T   T   T   T                      |
|                                     6 1,1 1,3 1,4 1,5 1,6                   |
|                      {0, 4} => -x T   T   T                                 |
|                                  6 1,1 1,4 1,5                              |
|                      {0, 6} => x T   T   T   T                              |
|                                 6 1,1 1,3 1,4 1,5                           |
|                      {0, 10} => -x T   T   T   T                            |
|                                   5 1,3 1,4 1,5 1,6                         |
|                      {0} => x T                                             |
|                              5 1,4                                          |
|                      {1, 0} => x T   T   T                                  |
|                                 5 1,3 1,4 1,5                               |
|                      {1, 2, 4} => -x T   T   T   T   T                      |
|                                     6 1,1 1,3 1,4 1,5 1,6                   |
|                      {1, 2} => x T   T   T                                  |
|                                 6 1,3 1,4 1,5                               |
|                      {1, 4, 2} => x T   T   T   T   T                       |
|                                    6 1,1 1,3 1,4 1,5 1,6                    |
|                      {1, 4} => -x T   T   T                                 |
|                                  6 1,1 1,3 1,5                              |
|                      {1, 8} => -x T   T   T   T                             |
|                                  6 1,1 1,3 1,4 1,5                          |
|                      {1, 9} => x T   T   T   T                              |
|                                 5 1,3 1,4 1,5 1,6                           |
|                      {1} => x T                                             |
|                              5 1,3                                          |
|                      {2, 1} => -x T   T   T                                 |
|                                  6 1,3 1,4 1,5                              |
|                      {2, 3} => -x T   T   T                                 |
|                                  6 1,3 1,4 1,6                              |
|                      {2, 4, 1} => x T   T   T   T   T                       |
|                                    6 1,1 1,3 1,4 1,5 1,6                    |
|                      {2, 4} => -x T   T   T                                 |
|                                  6 1,1 1,4 1,6                              |
|                      {2, 6} => x T   T   T   T                              |
|                                 6 1,1 1,3 1,4 1,6                           |
|                      {2, 10} => -x T   T   T   T                            |
|                                   6 1,3 1,4 1,5 1,6                         |
|                      {2} => x T                                             |
|                              6 1,4                                          |
|                      {3, 0} => x T   T   T                                  |
|                                 6 1,3 1,4 1,5                               |
|                      {3, 2} => x T   T   T                                  |
|                                 6 1,3 1,4 1,6                               |
|                      {3, 4, 0} => -x T   T   T   T   T                      |
|                                     6 1,1 1,3 1,4 1,5 1,6                   |
|                      {3, 4} => -x T   T   T                                 |
|                                  6 1,1 1,3 1,6                              |
|                      {3, 8} => -x T   T   T   T                             |
|                                  6 1,1 1,3 1,4 1,6                          |
|                      {3, 9} => x T   T   T   T                              |
|                                 6 1,3 1,4 1,5 1,6                           |
|                      {3} => x T                                             |
|                              6 1,3                                          |
|                      {4, 0} => x T   T   T                                  |
|                                 6 1,1 1,4 1,5                               |
|                      {4, 1} => x T   T   T                                  |
|                                 6 1,1 1,3 1,5                               |
|                      {4, 2, 1} => -x T   T   T   T   T                      |
|                                     6 1,1 1,3 1,4 1,5 1,6                   |
|                      {4, 2} => x T   T   T                                  |
|                                 6 1,1 1,4 1,6                               |
|                      {4, 3, 0} => x T   T   T   T   T                       |
|                                    6 1,1 1,3 1,4 1,5 1,6                    |
|                      {4, 3} => x T   T   T                                  |
|                                 6 1,1 1,3 1,6                               |
|                      {4, 5} => x T   T   T   T                              |
|                                 6 1,1 1,3 1,4 1,5                           |
|                      {4, 7} => x T   T   T   T                              |
|                                 6 1,1 1,3 1,4 1,6                           |
|                      {4, 9} => x T   T   T   T                              |
|                                 6 1,1 1,4 1,5 1,6                           |
|                      {4, 10} => x T   T   T   T                             |
|                                  6 1,1 1,3 1,5 1,6                          |
|                      {4, 12} => x T   T   T   T   T                         |
|                                  6 1,1 1,3 1,4 1,5 1,6                      |
|                      {4} => x T                                             |
|                              6 1,1                                          |
|                      {5, 4} => -x T   T   T   T                             |
|                                  6 1,1 1,3 1,4 1,5                          |
|                      {5} => -x T   T                                        |
|                               5 1,3 1,4                                     |
|                      {6, 0} => -x T   T   T   T                             |
|                                  6 1,1 1,3 1,4 1,5                          |
|                      {6, 2} => -x T   T   T   T                             |
|                                  6 1,1 1,3 1,4 1,6                          |
|                      {6, 9} => -x T   T   T   T   T                         |
|                                  6 1,1 1,3 1,4 1,5 1,6                      |
|                      {6} => -x T   T                                        |
|                               6 1,1 1,3                                     |
|                      {7, 4} => -x T   T   T   T                             |
|                                  6 1,1 1,3 1,4 1,6                          |
|                      {7} => -x T   T                                        |
|                               6 1,3 1,4                                     |
|                      {8, 1} => x T   T   T   T                              |
|                                 6 1,1 1,3 1,4 1,5                           |
|                      {8, 3} => x T   T   T   T                              |
|                                 6 1,1 1,3 1,4 1,6                           |
|                      {8, 10} => x T   T   T   T   T                         |
|                                  6 1,1 1,3 1,4 1,5 1,6                      |
|                      {8} => -x T   T                                        |
|                               6 1,1 1,4                                     |
|                      {9, 1} => -x T   T   T   T                             |
|                                  5 1,3 1,4 1,5 1,6                          |
|                      {9, 3} => -x T   T   T   T                             |
|                                  6 1,3 1,4 1,5 1,6                          |
|                      {9, 4} => -x T   T   T   T                             |
|                                  6 1,1 1,4 1,5 1,6                          |
|                      {9, 6} => -x T   T   T   T   T                         |
|                                  6 1,1 1,3 1,4 1,5 1,6                      |
|                      {9} => - x T   T    + x T   T                          |
|                                6 1,4 1,5    5 1,4 1,6                       |
|                      {10, 0} => x T   T   T   T                             |
|                                  5 1,3 1,4 1,5 1,6                          |
|                      {10, 2} => x T   T   T   T                             |
|                                  6 1,3 1,4 1,5 1,6                          |
|                      {10, 4} => -x T   T   T   T                            |
|                                   6 1,1 1,3 1,5 1,6                         |
|                      {10, 8} => x T   T   T   T   T                         |
|                                  6 1,1 1,3 1,4 1,5 1,6                      |
|                      {10} => - x T   T    + x T   T                         |
|                                 6 1,3 1,5    5 1,3 1,6                      |
|                      {11} => x T   T   T                                    |
|                               6 1,1 1,3 1,4                                 |
|                      {12, 4} => -x T   T   T   T   T                        |
|                                   6 1,1 1,3 1,4 1,5 1,6                     |
|                      {12} => x T   T   T    - x T   T   T                   |
|                               6 1,3 1,4 1,5    5 1,3 1,4 1,6                |
|                                                                             |
|o7 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i8 : assert(hasTMO)                                                          |
+-----------------------------------------------------------------------------+

Below is an example of a Teter ring (Artinian Gorenstein ring modulo its
socle), and the computation in Avramov and Levin's paper shows that H(A) does
not have trivial multiplication, hence no trivial Massey operation can exist.

+-----------------------------------------------------------------------------+
|i9 : Q = ZZ/101[x,y,z]                                                       |
|                                                                             |
|o9 = Q                                                                       |
|                                                                             |
|o9 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i10 : I = ideal (x^3,y^3,z^3,x^2*y^2*z^2)                                    |
|                                                                             |
|              3   3   3   2 2 2                                              |
|o10 = ideal (x , y , z , x y z )                                             |
|                                                                             |
|o10 : Ideal of Q                                                             |
+-----------------------------------------------------------------------------+
|i11 : R = Q/I                                                                |
|                                                                             |
|o11 = R                                                                      |
|                                                                             |
|o11 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i12 : A = koszulComplexDGA(R)                                                |
|                                                                             |
|o12 = {Ring => R                          }                                  |
|       Underlying algebra => R[T   ..T   ]                                   |
|                                1,1   1,3                                    |
|       Differential => {x, y, z}                                             |
|                                                                             |
|o12 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i13 : isHomologyAlgebraTrivial(A)                                            |
|                                                                             |
|o13 = false                                                                  |
+-----------------------------------------------------------------------------+
|i14 : cycleList = getGenerators(A)                                           |
|                                                                             |
|        2       2       2         2 2         2 2           2   2            |
|o14 = {x T   , y T   , z T   , x*y z T   , x*y z T   T   , x y*z T   T   ,   |
|          1,1     1,2     1,3         1,1         1,1 1,2         1,1 1,2    |
|      -----------------------------------------------------------------------|
|         2 2             2 2               2   2                             |
|      x*y z T   T   , x*y z T   T   T   , x y*z T   T   T   ,                |
|             1,1 1,3         1,1 1,2 1,3         1,1 1,2 1,3                 |
|      -----------------------------------------------------------------------|
|       2 2                                                                   |
|      x y z*T   T   T   }                                                    |
|             1,1 1,2 1,3                                                     |
|                                                                             |
|o14 : List                                                                   |
+-----------------------------------------------------------------------------+
|i15 : assert(not first findTrivialMasseyOperation(A))                        |
+-----------------------------------------------------------------------------+

The related function findNaryTrivialMasseyOperation,
find only the nth order trivial Massey operations.

Ways to use findTrivialMasseyOperation:
=======================================

  * "findTrivialMasseyOperation(DGAlgebra)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8556:0.

findTrivialMasseyOperation(...,GenDegreeLimit=>...) -- Maximum homological degree of generators used in the trivial Massey operation search
*******************************************************************************************************************************************

  * Usage:
        findTrivialMasseyOperation(..., GenDegreeLimit => n)

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

See GenDegreeLimit.

See also
========

  * findTrivialMasseyOperation -- Finds a
    trivial Massey operation on a set of generators of H(A)
  * GenDegreeLimit -- Option to bound the homological
    degree searched for algebra generators
  * TMOLimit -- Option to bound the arity of Massey operations
    searched for by findTrivialMasseyOperation

Functions with optional argument named GenDegreeLimit:
======================================================

  * findTrivialMasseyOperation(...,GenDegreeLimit=>...),
    --
    Maximum homological degree of generators used in the trivial Massey
    operation search
  * homologyAlgebra(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree searched for homology-algebra generators
  * isGolodHomomorphism(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree of generators used by isGolodHomomorphism
  * isHomologyAlgebraTrivial(...,GenDegreeLimit=>...),
    --
    Maximum homological degree of generators used by isHomologyAlgebraTrivial
  * torAlgebra(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree searched for Tor-algebra generators
  * "torMap(...,GenDegreeLimit=>...)" -- see torMap, -- Compute
    the map of Tor algebras associated to a RingMap.

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

  * Default value: infinity (Macaulay2Doc),
  * Function: findTrivialMasseyOperation, --
    Finds a trivial Massey operation on a set of generators of H(A)
  * Option key: GenDegreeLimit, -- Option to bound the
    homological degree searched for algebra generators
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9688:0.

findTrivialMasseyOperation(...,TMOLimit=>...) -- Maximum arity of Massey products searched for bounding
*******************************************************************************************************

  * Usage:
        findTrivialMasseyOperation(..., TMOLimit => n)

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

See TMOLimit.

See also
========

  * findTrivialMasseyOperation -- Finds a
    trivial Massey operation on a set of generators of H(A)
  * TMOLimit -- Option to bound the arity of Massey operations
    searched for by findTrivialMasseyOperation

Functions with optional argument named TMOLimit:
================================================

  * findTrivialMasseyOperation(...,TMOLimit=>...)
    -- Maximum
    arity of Massey products searched for bounding
  * isGolodHomomorphism(...,TMOLimit=>...)
    -- Option to cap
    the arity of the trivial Massey operation used in isGolodHomomorphism

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

  * Default value: infinity (Macaulay2Doc),
  * Function: findTrivialMasseyOperation, --
    Finds a trivial Massey operation on a set of generators of H(A)
  * Option key: TMOLimit, -- Option to bound the arity of
    Massey operations searched for by findTrivialMasseyOperation
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9703:0.

freeDGAlgebra -- Construct a free DG algebra with given generator degrees
*************************************************************************

  * Usage:
        A = freeDGAlgebra(R, degreeList)
        A = freeDGAlgebra(R, degreeList, Variable => "U")
  * Inputs:
      * R, a ring (Macaulay2Doc), The base ring over which the DG
        algebra is defined.
      * degreeList, a list (Macaulay2Doc), One degree per algebra
        generator.  Each degree is itself a List (Macaulay2Doc), of
        integers; the first entry is interpreted as the homological degree, and
        any remaining entries are internal gradings carried through to the
        underlying algebra.
  * Optional inputs (Macaulay2Doc),:
      * Variable => a string (Macaulay2Doc), default value "T",
        Either a base name (see String (Macaulay2Doc), or
        Symbol (Macaulay2Doc)) or an explicit list of symbols.
        Defaults to "T".  See below.
  * Outputs:
      * A, an instance of the type DGAlgebra, A DG algebra
        over R whose A.natural is a graded-commutative polynomial ring on
        #degreeList generators.  The differential is not set by this
        constructor; call setDiff, on the result to install it.

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

The output is a DGAlgebra, whose underlying ring is a
polynomial ring in graded-commutative generators: generators of odd homological
degree are skew-commutative and square to zero (i.e.\ exterior), while
generators of even homological degree are fully commutative.  The resulting
algebra is always free as a graded R-algebra; the current version of the
package does not handle quotient DG algebras whose underlying ring is a
non-polynomial quotient.

Variable-naming convention.  Generators are named base_(i, j), where i is the
homological degree (the first entry of the degree vector) and j is a 1-indexed
counter among generators at that hom-degree. So freeDGAlgebra(R, {{1}, {1},
{1}, {3}}) produces four generators T_(1,1), T_(1,2), T_(1,3), T_(3,1).  The
Variable option changes the base name:

+----------------------------------------------------------------+
|i1 : R = ZZ/101[x, y, z]                                        |
|                                                                |
|o1 = R                                                          |
|                                                                |
|o1 : PolynomialRing                                             |
+----------------------------------------------------------------+
|i2 : A = freeDGAlgebra(R, {{1}, {1}, {1}, {3}}, Variable => "U")|
|                                                                |
|o2 = {Ring => R                                }                |
|      Underlying algebra => R[U   ..U   , U   ]                 |
|                               1,1   1,3   3,1                  |
|      Differential => null                                      |
|                                                                |
|o2 : DGAlgebra                                                  |
+----------------------------------------------------------------+
|i3 : gens A.natural                                             |
|                                                                |
|o3 = {U   , U   , U   , U   }                                   |
|       1,1   1,2   1,3   3,1                                    |
|                                                                |
|o3 : List                                                       |
+----------------------------------------------------------------+

Passing a List (Macaulay2Doc), of symbols for Variable overrides the
doubly-indexed naming entirely and uses the given names verbatim.  The list
length must match #degreeList:

+-----------------------------------------------------------------------------+
|i4 : B = freeDGAlgebra(R, {{1}, {1}, {1}}, Variable => {getSymbol "P",       |
|                                                                             |
|o4 = {Ring => R                        }                                     |
|      Underlying algebra => R[P..Q, RR]                                      |
|      Differential => null                                                   |
|                                                                             |
|o4 : DGAlgebra                                                               |
|-----------------------------------------------------------------------------|
|getSymbol "Q", getSymbol "RR"})                                              |
+-----------------------------------------------------------------------------+
|i5 : gens B.natural                                                          |
|                                                                             |
|o5 = {P, Q, RR}                                                              |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

This is the mode used internally by adjoinVariables, and
acyclicClosure, to preserve the identities of existing
generators when extending a DG algebra.

Multi-grading.  Any degree entries beyond the first are carried through as
additional gradings of the underlying ring A.natural.  To make the differential
homogeneous with respect to both the homological and internal gradings, pair
each hom-degree with the matching internal-degree of its image under
setDiff.  Here, T_(1,i) has degree (1,1) (hom-degree 1,
internal-degree 1) matching x, y, z, and T_(3,1) has degree (3,3) matching its
cubic-monomial differential:

+-----------------------------------------------------------------------------+
|i6 : Bmulti = freeDGAlgebra(R, {{1, 1}, {1, 1}, {1, 1}, {3, 3}})             |
|                                                                             |
|o6 = {Ring => R                                }                             |
|      Underlying algebra => R[T   ..T   , T   ]                              |
|                               1,1   1,3   3,1                               |
|      Differential => null                                                   |
|                                                                             |
|o6 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i7 : degrees Bmulti.natural                                                  |
|                                                                             |
|o7 = {{1, 1}, {1, 1}, {1, 1}, {3, 3}}                                        |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : setDiff(Bmulti, {x, y, z, x*T_(1,2)*T_(1,3) - y*T_(1,1)*T_(1,3) +       |
|                                                                             |
|o8 = {Ring => R                                                      }       |
|      Underlying algebra => R[T   ..T   , T   ]                              |
|                               1,1   1,3   3,1                               |
|      Differential => {x, y, z, z*T   T    - y*T   T    + x*T   T   }        |
|                                   1,1 1,2      1,1 1,3      1,2 1,3         |
|                                                                             |
|o8 : DGAlgebra                                                               |
|-----------------------------------------------------------------------------|
|z*T_(1,1)*T_(1,2)})                                                          |
+-----------------------------------------------------------------------------+
|i9 : isHomogeneous Bmulti                                                    |
|                                                                             |
|o9 = true                                                                    |
+-----------------------------------------------------------------------------+

Dropping the internal grading (hom-degree only) breaks homogeneity because the
differential mixes different internal polynomial degrees of R:

+-----------------------------------------------------------------------------+
|i10 : Bhomo = freeDGAlgebra(R, {{1}, {1}, {1}, {3}})                         |
|                                                                             |
|o10 = {Ring => R                                }                            |
|       Underlying algebra => R[T   ..T   , T   ]                             |
|                                1,1   1,3   3,1                              |
|       Differential => null                                                  |
|                                                                             |
|o10 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i11 : setDiff(Bhomo, {x, y, z, x*T_(1,2)*T_(1,3) - y*T_(1,1)*T_(1,3) + z*T_(1|
|                                                                             |
|o11 = {Ring => R                                                      }      |
|       Underlying algebra => R[T   ..T   , T   ]                             |
|                                1,1   1,3   3,1                              |
|       Differential => {x, y, z, z*T   T    - y*T   T    + x*T   T   }       |
|                                    1,1 1,2      1,1 1,3      1,2 1,3        |
|                                                                             |
|o11 : DGAlgebra                                                              |
|-----------------------------------------------------------------------------|
|,1)*T_(1,2)})                                                                |
+-----------------------------------------------------------------------------+
|i12 : isHomogeneous Bhomo                                                    |
|                                                                             |
|o12 = false                                                                  |
+-----------------------------------------------------------------------------+

The differential is set after construction (via setDiff) rather
than passed to freeDGAlgebra directly: the differential's ring is A.natural,
which does not exist until after the constructor runs.  For common DG algebras
arising in commutative algebra (Koszul complex, Tate resolution, acyclic
closure, etc.) dedicated constructors are available; see
koszulComplexDGA, acyclicClosure,
minimalModel.

Caveat
======

There is currently a bug handling DG algebras that have no generators in some
homological degree but some in a later homological degree; for example
freeDGAlgebra(R, {{1}, {5}}) may produce incorrect behavior if no hom-degree 3
generators are adjoined first.  The safer workflow is freeDGAlgebra with
hom-degrees only up to what is needed, followed by adjoinVariables,
to extend incrementally.

See also
========

  * koszulComplexDGA -- The Koszul complex on the
    variables of a ring, as a DG algebra
  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension
  * minimalModel -- Build the minimal DG algebra
    resolution of a quotient ring
  * adjoinVariables -- Extend a DG algebra by a
    user-chosen list of cycles to be killed
  * setDiff -- Install or replace the differential on a DG
    algebra
  * DGAlgebra -- The class of all DGAlgebras

Ways to use freeDGAlgebra:
==========================

  * "freeDGAlgebra(Ring,List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:851:0.

GenDegreeLimit -- Option to bound the homological degree searched for algebra generators
****************************************************************************************

  * Usage:
        homologyAlgebra(..., GenDegreeLimit => n)
        torAlgebra(..., GenDegreeLimit => n)
        findTrivialMasseyOperation(..., GenDegreeLimit => n)
        isHomologyAlgebraTrivial(..., GenDegreeLimit => n)
        isGolodHomomorphism(..., GenDegreeLimit => n)

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

Routines that assemble a homology algebra — such as homologyAlgebra,
and torAlgebra, — must, in general, walk up
all homological degrees to find algebra generators.  When the DG algebra has
generators in even degree, that process is infinite; GenDegreeLimit caps the
search.  The answer is a truncation of the full homology algebra below the
specified degree, and is exact in the bounded case.

See also
========

  * RelDegreeLimit -- Option to bound the homological
    degree searched for algebra relations
  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.
  * torAlgebra -- Computes the Tor algebra of a ring
  * findTrivialMasseyOperation -- Finds a
    trivial Massey operation on a set of generators of H(A)
  * isHomologyAlgebraTrivial -- Determines if
    the homology algebra of a DGAlgebra is trivial
  * isGolodHomomorphism -- Determines if the
    canonical map from the ambient ring is Golod

Functions with optional argument named GenDegreeLimit:
======================================================

  * findTrivialMasseyOperation(...,GenDegreeLimit=>...),
    --
    Maximum homological degree of generators used in the trivial Massey
    operation search
  * homologyAlgebra(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree searched for homology-algebra generators
  * isGolodHomomorphism(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree of generators used by isGolodHomomorphism
  * isHomologyAlgebraTrivial(...,GenDegreeLimit=>...),
    --
    Maximum homological degree of generators used by isHomologyAlgebraTrivial
  * torAlgebra(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree searched for Tor-algebra generators
  * "torMap(...,GenDegreeLimit=>...)" -- see torMap, -- Compute
    the map of Tor algebras associated to a RingMap.

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

The object GenDegreeLimit, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9383:0.

getBasis -- Get a basis for a particular homological degree of a DG algebra.
****************************************************************************

  * Usage:
        M = getBasis(n,A)
  * Inputs:
      * n, an integer (Macaulay2Doc),
      * A, an instance of the type DGAlgebra,
  * Optional inputs (Macaulay2Doc),:
      * Limit, => ...,
        default value -1, Maximum number of basis elements to return from
        getBasis
  * Outputs:
      * M, a matrix (Macaulay2Doc), The basis of the desired
        homological degree of the DG Algebra.

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

This function is to allow for the retrieval of a basis of a particular
homological degree of a DGAlgebra, when the underlying algebra
A.natural is multigraded.  In the code, the homological grading is always the
first integer in the degree tuple, and so this function returns a matrix
consisting of all monomials in homological degree n.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a..d, Degrees=>{1,1,1,2}]                                    |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : A =  koszulComplexDGA(R)                                                |
|                                                                             |
|o2 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,4                                     |
|      Differential => {a, b, c, d}                                           |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : getBasis(3,A)                                                           |
|                                                                             |
|o3 = | T_(1,1)T_(1,2)T_(1,3) T_(1,1)T_(1,2)T_(1,4) T_(1,1)T_(1,3)T_(1,4)     |
|     ------------------------------------------------------------------------|
|     T_(1,2)T_(1,3)T_(1,4) |                                                 |
|                                                                             |
|                           1                    4                            |
|o3 : Matrix (R[T   ..T   ])  <-- (R[T   ..T   ])                             |
|                1,1   1,4            1,1   1,4                               |
+-----------------------------------------------------------------------------+

Ways to use getBasis:
=====================

  * "getBasis(ZZ,DGAlgebra)"
  * getBasis(ZZ,DGModule) -- Basis of the
    hom-degree-n piece of a DG module
  * getBasis(ZZ,Ring) -- Get a basis for a
    degree of a ring.

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1258:0.

getBasis(...,Limit=>...) -- Maximum number of basis elements to return from getBasis
************************************************************************************

  * Usage:
        getBasis(..., Limit => n)

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

Caps the size of the returned basis, which is useful when only the first few
elements are needed (for example, when enumerating cycles degree by degree).

See also
========

  * getBasis -- Get a basis for a particular homological
    degree of a DG algebra.

Functions with optional argument named Limit:
=============================================

  * "basis(...,Limit=>...)" -- see basis (Macaulay2Doc), -- basis
    or generating set of all or part of a ring, ideal or module
  * getBasis(...,Limit=>...),
    -- Maximum number of basis elements to return from getBasis
  * icFracP(...,Limit=>...) (IntegralClosure)
    -- Limits the
    number of computed intermediate modules.
  * "independentSets(...,Limit=>...)" -- see independentSets (Macaulay2Doc),
    -- some size-maximal independent subsets of
    variables modulo an ideal
  * integralClosure(...,Limit=>...) (IntegralClosure)
    -- do a
    partial integral closure
  * "minors(...,Limit=>...)" -- see minors(ZZ,Matrix) (Macaulay2Doc),
    -- ideal generated by minors

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

  * Default value: -1
  * Function: getBasis, -- Get a basis for a particular
    homological degree of a DG algebra.
  * Option key: Limit (Macaulay2Doc), -- an optional argument
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9608:0.

getBasis(ZZ,Ring) -- Get a basis for a degree of a ring.
********************************************************

  * Function: getBasis,
  * Usage:
        M = getBasis(n,R)
  * Inputs:
      * n, an integer (Macaulay2Doc),
      * R, a ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Limit, => ...,
        default value -1, Maximum number of basis elements to return from
        getBasis
  * Outputs:
      * M, a matrix (Macaulay2Doc), The basis of the desired
        degree

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

This function was not meant for general use, but it fixes the first degree in
the degree tuple of the ring R, and finds a basis of that 'slice' of the ring.
It does this by using a cached version of the ring that forgets all other
degrees.  A Ring object in Macaulay2 will not have this cached ring by default,
but the rings used internally in the DGAlgebras package will.

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

  * getBasis(ZZ,Ring) -- Get a basis for a
    degree of a ring.
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1279:0.

getBoundaryPreimage -- Attempt to find a preimage of a boundary under the differential of a DGAlgebra.
******************************************************************************************************

  * Usage:
        (lifted,myLift) = getBoundaryPreimage(A,z)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * z, a ring element (Macaulay2Doc),
  * Outputs:
      * seq, a sequence (Macaulay2Doc),

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

The first element in the return value is a boolean value indicating whether the
lift was possible.  If true, the second coordinate of the return value is the
lift. If false, then the second coordinate of the return value is the reduction
of the input modulo the image.

+-----------------------------------------------------------------------------+
|i1 : Q = QQ[x_1,x_2,y_1,y_2,z]                                               |
|                                                                             |
|o1 = Q                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal (x_1*x_2^2,y_1*y_2^2,z^3,x_1*x_2*y_1*y_2,y_2^2*z^2,x_2^2*z^2,x|
|                                                                             |
|               2     2   3             2 2   2 2          2 2                |
|o2 = ideal (x x , y y , z , x x y y , y z , x z , x y z, x y z)              |
|             1 2   1 2       1 2 1 2   2     2     1 1    2 2                |
|                                                                             |
|o2 : Ideal of Q                                                              |
|-----------------------------------------------------------------------------|
|_1*y_1*z,x_2^2*y_2^2*z)                                                      |
+-----------------------------------------------------------------------------+
|i3 : R = Q/I                                                                 |
|                                                                             |
|o3 = R                                                                       |
|                                                                             |
|o3 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i4 : KR = koszulComplexDGA R                                                 |
|                                                                             |
|o4 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,5                                     |
|      Differential => {x , x , y , y , z}                                    |
|                        1   2   1   2                                        |
|                                                                             |
|o4 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+

The following are cycles:

+------------------------------------------+
|i5 : z1 = z^2*T_(1,5)                     |
|                                          |
|      2                                   |
|o5 = z T                                  |
|        1,5                               |
|                                          |
|o5 : R[T   ..T   ]                        |
|        1,1   1,5                         |
+------------------------------------------+
|i6 : z2 = y_2^2*T_(1,3)                   |
|                                          |
|      2                                   |
|o6 = y T                                  |
|      2 1,3                               |
|                                          |
|o6 : R[T   ..T   ]                        |
|        1,1   1,5                         |
+------------------------------------------+
|i7 : z3 = x_2^2*T_(1,1)                   |
|                                          |
|      2                                   |
|o7 = x T                                  |
|      2 1,1                               |
|                                          |
|o7 : R[T   ..T   ]                        |
|        1,1   1,5                         |
+------------------------------------------+
|i8 : {diff(KR,z1),diff(KR,z1),diff(KR,z1)}|
|                                          |
|o8 = {0, 0, 0}                            |
|                                          |
|o8 : List                                 |
+------------------------------------------+

and z1*z2, z2*z3 vanish in homology:

+-------------------------------------------------------+
|i9 : (lifted12,lift12) = getBoundaryPreimage(KR,z1*z2) |
|                                                       |
|o9 = (true, 0)                                         |
|                                                       |
|o9 : Sequence                                          |
+-------------------------------------------------------+
|i10 : (lifted23,lift23) = getBoundaryPreimage(KR,z2*z3)|
|                                                       |
|                2                                      |
|o10 = (true, x y T   T   T    - x x y T   T   T   )    |
|              2 2 1,1 1,2 1,3    1 2 2 1,2 1,3 1,4     |
|                                                       |
|o10 : Sequence                                         |
+-------------------------------------------------------+

We can check that the differential of the lift is the supposed boundary:

+------------------------------+
|i11 : diff(KR,lift23) == z2*z3|
|                              |
|o11 = true                    |
+------------------------------+

Ways to use getBoundaryPreimage:
================================

  * "getBoundaryPreimage(DGAlgebra,List)"
  * "getBoundaryPreimage(DGAlgebra,RingElement)"
  * getBoundaryPreimage(DGModule,List)
    -- Lift a list of boundaries
    sharing a hom-degree through the module differential
  * getBoundaryPreimage(DGModule,Vector)
    -- Lift a boundary in a DG
    module to a preimage under the differential

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8810:0.

getDegNModule -- Extract the degree-n strand of a graded algebra as a module over its degree-zero piece
*******************************************************************************************************

  * Usage:
        MN = getDegNModule(N, R, A)
  * Inputs:
      * N, an integer (Macaulay2Doc), the homological degree to
        extract
      * R, a ring (Macaulay2Doc), the degree-zero piece of A, i.e.\
        A_0
      * A, a ring (Macaulay2Doc), a graded R-algebra with A_0 = R
  * Outputs:
      * MN, a module (Macaulay2Doc), the degree-N component of A,
        presented as an R-module

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

Given a graded algebra A over R with A_0 = R, the strand A_N is an R-module.
This function returns that strand with a minimal presentation by monomials of
internal degree N modulo the relations of A.  It is most often applied to a
homology algebra HA = HH A together with its degree-zero subring HA_0 =
zerothHomology A.

+-----------------------------------------------------------------------------+
|i1 : Q = ZZ/101[x,y,z]                                                       |
|                                                                             |
|o1 = Q                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(x^3, y^3, z^3)                                                |
|                                                                             |
|             3   3   3                                                       |
|o2 = ideal (x , y , z )                                                      |
|                                                                             |
|o2 : Ideal of Q                                                              |
+-----------------------------------------------------------------------------+
|i3 : R = Q / I                                                               |
|                                                                             |
|o3 = R                                                                       |
|                                                                             |
|o3 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i4 : KR = koszulComplexDGA R                                                 |
|                                                                             |
|o4 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,3                                     |
|      Differential => {x, y, z}                                              |
|                                                                             |
|o4 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i5 : HA = HH KR;                                                             |
|Finding easy relations           :  -- used 0.0196563s (cpu); 0.0186863s     |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i6 : H0 = zerothHomology KR                                                  |
|                                                                             |
|o6 = H0                                                                      |
|                                                                             |
|o6 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i7 : M1 = getDegNModule(1, H0, HA)                                           |
|                                                                             |
|       3                                                                     |
|o7 = H0                                                                      |
|                                                                             |
|o7 : H0-module, free                                                         |
+-----------------------------------------------------------------------------+
|i8 : M2 = getDegNModule(2, H0, HA)                                           |
|                                                                             |
|       3                                                                     |
|o8 = H0                                                                      |
|                                                                             |
|o8 : H0-module, free                                                         |
+-----------------------------------------------------------------------------+

The ranks of these strands are the Koszul Betti numbers of R:

+-------------------------------------------------------+
|i9 : apply(0..3, n -> numgens getDegNModule(n, H0, HA))|
|                                                       |
|o9 = (1, 3, 3, 1)                                      |
|                                                       |
|o9 : Sequence                                          |
+-------------------------------------------------------+

See also
========

  * zerothHomology -- The zeroth homology of a DG
    algebra as a ring
  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.
  * homologyModule -- Compute the homology of a DGModule
    as a module over a DGAlgebra.

Ways to use getDegNModule:
==========================

  * "getDegNModule(ZZ,Ring,Ring)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8919:0.

getGenerators -- Cycles whose classes generate the homology algebra of a DG algebra
***********************************************************************************

  * Usage:
        cycleList = getGenerators A
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Optional inputs (Macaulay2Doc),:
      * DegreeLimit,
        => ..., default value -1, Last homological degree in which to
        search for algebra generators
      * StartDegree,
        => ..., default value 1, First homological degree in which to
        search for new algebra generators
      * Verbosity,
        => ..., default value 0, Option to control progress output from
        getGenerators
  * Outputs:
      * cycleList, a list (Macaulay2Doc), a list of cycles in
        A.natural whose homology classes generate HH_*(A) as a
        graded-commutative algebra over A.ring

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

Walks up the homological degrees of A, computing a basis of each homology
module and selecting minimal new generators not already reachable by products
of lower-degree cycles.  The returned list is exactly the generating set used
internally by homologyAlgebra, to build its
presentation.

This version of the function assumes all algebra generators of A lie in odd
homological degree.  When A has generators in even degree, a finite generating
set need not exist, and the search depth must be bounded with EndDegree or
GenDegreeLimit.

+----------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c] / ideal(a^3, b^3, c^3, a^2*b^2*c^2)|
|                                                          |
|o1 = R                                                    |
|                                                          |
|o1 : QuotientRing                                         |
+----------------------------------------------------------+
|i2 : A = koszulComplexDGA R                               |
|                                                          |
|o2 = {Ring => R                          }                |
|      Underlying algebra => R[T   ..T   ]                 |
|                               1,1   1,3                  |
|      Differential => {a, b, c}                           |
|                                                          |
|o2 : DGAlgebra                                            |
+----------------------------------------------------------+
|i3 : netList getGenerators A                              |
|                                                          |
|     +------------------+                                 |
|     | 2                |                                 |
|o3 = |a T               |                                 |
|     |   1,1            |                                 |
|     +------------------+                                 |
|     | 2                |                                 |
|     |b T               |                                 |
|     |   1,2            |                                 |
|     +------------------+                                 |
|     | 2                |                                 |
|     |c T               |                                 |
|     |   1,3            |                                 |
|     +------------------+                                 |
|     |   2 2            |                                 |
|     |a*b c T           |                                 |
|     |       1,1        |                                 |
|     +------------------+                                 |
|     |   2 2            |                                 |
|     |a*b c T   T       |                                 |
|     |       1,1 1,2    |                                 |
|     +------------------+                                 |
|     | 2   2            |                                 |
|     |a b*c T   T       |                                 |
|     |       1,1 1,2    |                                 |
|     +------------------+                                 |
|     |   2 2            |                                 |
|     |a*b c T   T       |                                 |
|     |       1,1 1,3    |                                 |
|     +------------------+                                 |
|     |   2 2            |                                 |
|     |a*b c T   T   T   |                                 |
|     |       1,1 1,2 1,3|                                 |
|     +------------------+                                 |
|     | 2   2            |                                 |
|     |a b*c T   T   T   |                                 |
|     |       1,1 1,2 1,3|                                 |
|     +------------------+                                 |
|     | 2 2              |                                 |
|     |a b c*T   T   T   |                                 |
|     |       1,1 1,2 1,3|                                 |
|     +------------------+                                 |
+----------------------------------------------------------+

The generators above are the cycles used to present homologyAlgebra A; their
classes span HH_i A in each positive degree.

+--------------------------------------------------------------+
|i4 : apply(maxDegree A + 1, i -> numgens prune homology(i, A))|
|                                                              |
|o4 = {1, 4, 6, 3}                                             |
|                                                              |
|o4 : List                                                     |
+--------------------------------------------------------------+

See also
========

  * DGAlgebra -- The class of all DGAlgebras
  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.
  * HH_ZZ DGAlgebra -- Computes the homology of a DG
    algebra as a module
  * homologyClass -- Computes the element of the homology
    algebra corresponding to a cycle in a DGAlgebra.

Ways to use getGenerators:
==========================

  * "getGenerators(DGAlgebra)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8433:0.

getGenerators(...,DegreeLimit=>...) -- Last homological degree in which to search for algebra generators
********************************************************************************************************

  * Usage:
        getGenerators(..., DegreeLimit => n)

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

Caps the homological degree of candidates considered by getGenerators.
When the underlying DG algebra has generators in even degree,
this option is required to make the search finite.

See also
========

  * getGenerators -- Cycles whose classes generate the
    homology algebra of a DG algebra
  * getGenerators(...,StartDegree=>...)
    -- First homological
    degree in which to search for new algebra generators

Functions with optional argument named DegreeLimit:
===================================================

  * "compose(Module,Module,Module,DegreeLimit=>...)" -- see compose (Macaulay2Doc),
    -- composition as a pairing on Hom-modules
  * deviations(...,DegreeLimit=>...)
    -- Maximum homological
    degree to which deviations are computed
  * "deviationsToPoincare(...,DegreeLimit=>...)" -- see
    deviationsToPoincare, -- Computes the power series
    corresponding to a set of deviations.
  * "End(...,DegreeLimit=>...)" -- see End (Macaulay2Doc), -- module
    of endomorphisms
  * epicResolutionMap(...,DegreeLimit=>...) (missing documentation)
  * "gb(...,DegreeLimit=>...)" -- see gb (Macaulay2Doc), -- compute a
    Gröbner basis
  * getGenerators(...,DegreeLimit=>...)
    -- Last homological
    degree in which to search for algebra generators
  * "Hom(...,DegreeLimit=>...)" -- see Hom (Macaulay2Doc), -- module
    of homomorphisms
  * "homomorphism'(...,DegreeLimit=>...)" -- see homomorphism' (Macaulay2Doc),
    -- get the element of Hom from a homomorphism
  * kernel(...,DegreeLimit=>...) (Macaulay2Doc)
    -- stop after
    finding enough elements of a subring
  * "minimalBetti(...,DegreeLimit=>...)" -- see minimalBetti (Macaulay2Doc),
    -- minimal betti numbers of (the minimal free
    resolution of) a homogeneous ideal or module
  * normalCone(Ideal,DegreeLimit=>...) (missing documentation)
  * normalCone(Ideal,RingElement,DegreeLimit=>...) (missing documentation)
  * "freeResolution(...,DegreeLimit=>...)" -- see Options for free resolutions (Complexes),
    -- optional arguments
    for freeResolution
  * "pushForward(...,DegreeLimit=>...)" -- see
    pushForward(RingMap,Module) (Macaulay2Doc),
    -- compute the pushforward
    of a module along a ring map
  * quotient(...,DegreeLimit=>...) (missing documentation)
  * "resolutionMap(...,DegreeLimit=>...)" -- see resolutionMap (Complexes),
    -- map from a free resolution to the given
    complex
  * saturate(...,DegreeLimit=>...) (missing documentation)
  * "syz(...,DegreeLimit=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix

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

  * Default value: -1
  * Function: getGenerators, -- Cycles whose classes
    generate the homology algebra of a DG algebra
  * Option key: DegreeLimit (Macaulay2Doc), -- an optional
    argument
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9505:0.

getGenerators(...,StartDegree=>...) -- First homological degree in which to search for new algebra generators
*************************************************************************************************************

  * Usage:
        getGenerators(..., StartDegree => n)

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

Degrees below n are skipped when walking getGenerators, up
through the DG algebra.  Raising StartDegree is useful when earlier degrees
have been inspected separately.  See StartDegree.

See also
========

  * getGenerators -- Cycles whose classes generate the
    homology algebra of a DG algebra
  * StartDegree -- Option to specify the first homological
    degree processed by an iterative DG construction
  * getGenerators(...,DegreeLimit=>...)
    -- Last homological
    degree in which to search for algebra generators

Functions with optional argument named StartDegree:
===================================================

  * acyclicClosure(...,StartDegree=>...)
    -- Option to
    specify the degree to start computing the acyclic closure.
  * getGenerators(...,StartDegree=>...)
    -- First homological
    degree in which to search for new algebra generators
  * killCycles(...,StartDegree=>...)
    -- First homological
    degree from which killCycles begins searching for cycles
  * "minimalModel(...,StartDegree=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * minimalSemifreeResolution(...,StartDegree=>...),
    --
    Option to specify the degree at which minimalSemifreeResolution starts
    killing cycles
  * semifreeResolution(...,StartDegree=>...)
    -- Option to
    specify the degree at which semifreeResolution starts killing cycles

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

  * Default value: 1
  * Function: getGenerators, -- Cycles whose classes
    generate the homology algebra of a DG algebra
  * Option key: StartDegree, -- Option to specify the first
    homological degree processed by an iterative DG construction
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9488:0.

getGenerators(...,Verbosity=>...) -- Option to control progress output from getGenerators
*****************************************************************************************

  * Usage:
        getGenerators(...,Verbosity=>n)

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

Larger values of n print progress messages about the cycle enumeration and
independence checks in getGenerators. The default is 0
(no output).

See also
========

  * getGenerators -- Cycles whose classes generate the
    homology algebra of a DG algebra

Functions with optional argument named Verbosity:
=================================================

  * getGenerators(...,Verbosity=>...)
    -- Option to control
    progress output from getGenerators
  * homologyAlgebra(...,Verbosity=>...)
    -- Option to control
    progress output from homologyAlgebra
  * icFracP(...,Verbosity=>...) (IntegralClosure)
    -- Prints
    out the conductor element and the number of intermediate modules it
    computed.
  * "idealizer(...,Verbosity=>...)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * integralClosure(...,Verbosity=>...) (IntegralClosure),
    --
    display a certain amount of detail about the computation
  * "isPrime(Ideal,Verbosity=>...)" -- see isPrime(Ideal) (MinimalPrimes),
    -- whether an ideal is prime
  * "makeS2(...,Verbosity=>...)" -- see makeS2 (IntegralClosure),
    -- compute the S2ification of a reduced ring
  * "decompose(Ideal,Verbosity=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,Verbosity=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "ringFromFractions(...,Verbosity=>...)" -- see ringFromFractions (IntegralClosure),
    -- find presentation for f.g. ring

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

  * Default value: 0
  * Function: getGenerators, -- Cycles whose classes
    generate the homology algebra of a DG algebra
  * Option key: Verbosity (missing documentation)
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9821:0.

HH DGAlgebra -- The homology algebra of a DG algebra
****************************************************

  * Function: homology (Macaulay2Doc),
  * Usage:
        HA = homology A
        HA = HH A
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Outputs:
      * HA, a ring (Macaulay2Doc), the homology algebra HH_*(A), as
        a graded-commutative ring

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

Returns the homology algebra of A, caching the result inside A so subsequent
calls are fast.  This is a convenience wrapper around homologyAlgebra,
that supports the HH shorthand.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c] / ideal(a^3, b^3, c^3, a^2*b^2*c^2)                   |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o2 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,3                                     |
|      Differential => {a, b, c}                                              |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : HA = HH A                                                               |
|Finding easy relations           :  -- used 0.0397408s (cpu); 0.0373805s     |
|                                                                             |
|o3 = HA                                                                      |
|                                                                             |
|o3 : QuotientRing                                                            |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i4 : numgens HA                                                              |
|                                                                             |
|o4 = 10                                                                      |
+-----------------------------------------------------------------------------+
|i5 : apply(maxDegree A + 1, i -> numgens prune homology(i, A))               |
|                                                                             |
|o5 = {1, 4, 6, 3}                                                            |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

For DG algebras with even-degree generators (such as acyclic closures of
non-regular rings), call homologyAlgebra, directly and
supply GenDegreeLimit, and RelDegreeLimit,
explicitly.

See also
========

  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.
  * zerothHomology -- The zeroth homology of a DG
    algebra as a ring
  * HH_ZZ DGAlgebra -- Computes the homology of a DG
    algebra as a module

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

  * HH DGAlgebra -- The homology algebra of a DG algebra
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8166:0.

HH DGAlgebraMap -- The induced ring map on homology algebras
************************************************************

  * Function: homology (Macaulay2Doc),
  * Usage:
        homologyPhi = homology phi
        homologyPhi = HH phi
  * Inputs:
      * phi, an instance of the type DGAlgebraMap,
  * Outputs:
      * homologyPhi, a ring map (Macaulay2Doc), the induced map
        HH(source phi) -> HH(target phi)

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

A DGAlgebraMap, phi: A -> B is a chain map, so it descends
to a ring map on homology algebras.  This function computes that induced map,
returning a RingMap (Macaulay2Doc), from homologyAlgebra,
of the source to homologyAlgebra, of
the target.  The homology algebras are computed via homologyAlgebra,
if they have not been cached.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c]/ideal{a^3 + b^3 + c^3, a*b*c}                         |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : K1 = koszulComplexDGA(ideal vars R, Variable => "Y")                    |
|                                                                             |
|o2 = {Ring => R                          }                                   |
|      Underlying algebra => R[Y   ..Y   ]                                    |
|                               1,1   1,3                                     |
|      Differential => {a, b, c}                                              |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : K2 = koszulComplexDGA(ideal{b, c}, Variable => "T")                     |
|                                                                             |
|o3 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,2                                     |
|      Differential => {b, c}                                                 |
|                                                                             |
|o3 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i4 : g = dgAlgebraMap(K1, K2, matrix{{Y_(1,2), Y_(1,3)}})                    |
|                                                                             |
|o4 = map (R[Y   ..Y   ], R[T   ..T   ], {Y   , Y   , a, b, c})               |
|             1,1   1,3      1,1   1,2     1,2   1,3                          |
|                                                                             |
|o4 : DGAlgebraMap                                                            |
+-----------------------------------------------------------------------------+
|i5 : HHg = HH g                                                              |
|Finding easy relations           :  -- used 0.0187517s (cpu); 0.0178841s     |
|                                                                             |
|                         ZZ                                                  |
|                        ---[a..c]                                            |
|           ZZ           101                                                  |
|o5 = map (---[X ..X ], ----------[X ], {X , 0, 0, 0})                        |
|          101  1   2           3   1     1                                   |
|                       (c, b, a )                                            |
|                                                                             |
|                               ZZ                                            |
|                              ---[a..c]                                      |
|              ZZ              101                                            |
|o5 : RingMap ---[X ..X ] <-- ----------[X ]                                  |
|             101  1   2              3   1                                   |
|                             (c, b, a )                                      |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i6 : source HHg === homologyAlgebra K1                                       |
|                                                                             |
|o6 = false                                                                   |
+-----------------------------------------------------------------------------+
|i7 : target HHg === homologyAlgebra K2                                       |
|                                                                             |
|o7 = false                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * DGAlgebraMap -- The class of DG algebra maps
  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.
  * toComplexMap -- Construct the ComplexMap associated to
    a DGAlgebraMap

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

  * HH DGAlgebraMap -- The induced ring map on homology
    algebras
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9127:0.

HH DGModuleMap -- The induced map on graded homology modules over HH(A)
***********************************************************************

  * Function: homology (Macaulay2Doc),
  * Usage:
        h = homology f
  * Inputs:
      * f, an instance of the type DGModuleMap, A morphism
        M -> N of DG modules over a common DG algebra A.  Both M.natural and
        N.natural must be free (the free / semifree case).
  * Outputs:
      * h, The induced A.homology-module map H_*(M) -> H_*(N), where H_*(M) and
        H_*(N) carry their natural HH(A)-module structures via the action of
        cycles of A on M and N.  The result lives over the ring HH(A).

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

The per-degree restrictions of h are given by homology(DGModuleMap,ZZ).
The present method assembles them into a
single map of HH(A)-modules by forming the direct sum of the per-degree pieces
and imposing the cycle-action relations on both sides.  Functorial in f.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y]/ideal(x^2, y^2)                                             |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o2 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,2                                     |
|      Differential => {x, y}                                                 |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : Mdg = minimalSemifreeResolution(A, R^1 / ideal(x,y), EndDegree => 2)    |
|                                                                             |
|o3 = {Base ring => R                                          }              |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       3                                     |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}}                          |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |}               |
|                                   |     0    |  |     0    |                |
|                                   |     0    |  |     0    |                |
|                                                                             |
|o3 : DGModule                                                                |
+-----------------------------------------------------------------------------+
|i4 : idM = identityDGModuleMap Mdg                                           |
|                                                                             |
|                               3                                             |
|o4 = {Source => (R[T   ..T   ])  }                                           |
|                    1,1   1,2                                                |
|                               3                                             |
|      Target => (R[T   ..T   ])                                              |
|                    1,1   1,2                                                |
|      Natural => {0, 0} | 1 0 0 |                                            |
|                 {2, 2} | 0 1 0 |                                            |
|                 {2, 2} | 0 0 1 |                                            |
|                                                                             |
|o4 : DGModuleMap                                                             |
+-----------------------------------------------------------------------------+
|i5 : h = homology idM                                                        |
|Finding easy relations           :  -- used 0.154562s (cpu); 0.0872498s      |
|                                                                             |
|o5 = {0, 0} | 1 0 0 0 |                                                      |
|     {3, 4} | 0 1 0 0 |                                                      |
|     {3, 4} | 0 0 1 0 |                                                      |
|     {3, 4} | 0 0 0 1 |                                                      |
|                                                                             |
|o5 : Matrix                                                                  |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i6 : ring source h === HH A                                                  |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * homology(DGModuleMap,ZZ) -- The
    induced map on degree-n homology of a DG module map
  * Basic operations on DG Module Maps
    -- Outlines some basic operations on DGModuleMaps

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

  * HH DGModuleMap -- The induced map on graded homology
    modules over HH(A)
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:515:0.

HH_ZZ DGAlgebra -- Computes the homology of a DG algebra as a module
********************************************************************

  * Function: homology (Macaulay2Doc),
  * Usage:
        H = homology(n,A)
  * Inputs:
      * n, an integer (Macaulay2Doc),
      * A, an instance of the type DGAlgebra,
  * Outputs:
      * H, a module (Macaulay2Doc), The nth homology of A.

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

+---------------------------------------------------------+
|i1 : R = ZZ/32003[x,y,z]                                 |
|                                                         |
|o1 = R                                                   |
|                                                         |
|o1 : PolynomialRing                                      |
+---------------------------------------------------------+
|i2 : A = koszulComplexDGA(R)                             |
|                                                         |
|o2 = {Ring => R                          }               |
|      Underlying algebra => R[T   ..T   ]                |
|                               1,1   1,3                 |
|      Differential => {x, y, z}                          |
|                                                         |
|o2 : DGAlgebra                                           |
+---------------------------------------------------------+
|i3 : apply(numgens R+1, i -> numgens prune homology(i,A))|
|                                                         |
|o3 = {1, 0, 0, 0}                                        |
|                                                         |
|o3 : List                                                |
+---------------------------------------------------------+

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

  * HH_ZZ DGAlgebra -- Computes the homology of a DG
    algebra as a module
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1038:0.

homologyAlgebra -- Compute the homology algebra of a DGAlgebra.
***************************************************************

  * Usage:
        HA = homologyAlgebra(A)
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Optional inputs (Macaulay2Doc),:
      * GenDegreeLimit,
        => ..., default value infinity, Maximum homological degree
        searched for homology-algebra generators
      * RelDegreeLimit,
        => ..., default value infinity, Maximum homological degree
        searched for homology-algebra relations
      * Verbosity,
        => ..., default value 0, Option to control progress output from
        homologyAlgebra
  * Outputs:
      * HA, a ring (Macaulay2Doc),

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

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c,d]/ideal{a^4,b^4,c^4,d^4}                              |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : A = koszulComplexDGA(R)                                                 |
|                                                                             |
|o2 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,4                                     |
|      Differential => {a, b, c, d}                                           |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : apply(maxDegree A + 1, i -> numgens prune homology(i,A))                |
|                                                                             |
|o3 = {1, 4, 6, 4, 1}                                                         |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : HA = homologyAlgebra(A)                                                 |
|Finding easy relations           :  -- used 0.0242623s (cpu); 0.0233152s     |
|                                                                             |
|o4 = HA                                                                      |
|                                                                             |
|o4 : PolynomialRing, 4 skew commutative variable(s)                          |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+

Note that HA is a graded commutative polynomial ring (i.e. an exterior algebra)
since R is a complete intersection.

+-----------------------------------------------------------------------------+
|i5 : R = ZZ/101[a,b,c,d]/ideal{a^4,b^4,c^4,d^4,a^3*b^3*c^3*d^3}              |
|                                                                             |
|o5 = R                                                                       |
|                                                                             |
|o5 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i6 : A = koszulComplexDGA(R)                                                 |
|                                                                             |
|o6 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,4                                     |
|      Differential => {a, b, c, d}                                           |
|                                                                             |
|o6 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i7 : apply(maxDegree A + 1, i -> numgens prune homology(i,A))                |
|                                                                             |
|o7 = {1, 5, 10, 10, 4}                                                       |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : HA = homologyAlgebra(A)                                                 |
|Finding easy relations           :  -- used 0.115128s (cpu); 0.112289s       |
|                                                                             |
|o8 = HA                                                                      |
|                                                                             |
|o8 : QuotientRing                                                            |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i9 : numgens HA                                                              |
|                                                                             |
|o9 = 19                                                                      |
+-----------------------------------------------------------------------------+
|i10 : HA.cache.cycles                                                        |
|                                                                             |
|        3       3       3       3       2 3 3 3       2 3 3 3                |
|o10 = {a T   , b T   , c T   , d T   , a b c d T   , a b c d T   T   ,       |
|          1,1     1,2     1,3     1,4           1,1           1,1 1,2        |
|      -----------------------------------------------------------------------|
|       3 2 3 3           2 3 3 3           2 3 3 3                           |
|      a b c d T   T   , a b c d T   T   , a b c d T   T   ,                  |
|               1,1 1,2           1,1 1,3           1,1 1,4                   |
|      -----------------------------------------------------------------------|
|       2 3 3 3               3 2 3 3               3 3 2 3                   |
|      a b c d T   T   T   , a b c d T   T   T   , a b c d T   T   T   ,      |
|               1,1 1,2 1,3           1,1 1,2 1,3           1,1 1,2 1,3       |
|      -----------------------------------------------------------------------|
|       2 3 3 3               3 2 3 3               2 3 3 3                   |
|      a b c d T   T   T   , a b c d T   T   T   , a b c d T   T   T   ,      |
|               1,1 1,2 1,4           1,1 1,2 1,4           1,1 1,3 1,4       |
|      -----------------------------------------------------------------------|
|       2 3 3 3                   3 2 3 3                                     |
|      a b c d T   T   T   T   , a b c d T   T   T   T   ,                    |
|               1,1 1,2 1,3 1,4           1,1 1,2 1,3 1,4                     |
|      -----------------------------------------------------------------------|
|       3 3 2 3                   3 3 3 2                                     |
|      a b c d T   T   T   T   , a b c d T   T   T   T   }                    |
|               1,1 1,2 1,3 1,4           1,1 1,2 1,3 1,4                     |
|                                                                             |
|o10 : List                                                                   |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i11 : Q = ZZ/101[x,y,z]                                                      |
|                                                                             |
|o11 = Q                                                                      |
|                                                                             |
|o11 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i12 : I = ideal{y^3,z*x^2,y*(z^2+y*x),z^3+2*x*y*z,x*(z^2+y*x),z*y^2,x^3,z*(z^|
|                                                                             |
|              3   2      2      2            3   2       2   2    3          |
|o12 = ideal (y , x z, x*y  + y*z , 2x*y*z + z , x y + x*z , y z, x , 2x*y*z +|
|      -----------------------------------------------------------------------|
|       3                                                                     |
|      z )                                                                    |
|                                                                             |
|o12 : Ideal of Q                                                             |
|-----------------------------------------------------------------------------|
|2+2*x*y)}                                                                    |
+-----------------------------------------------------------------------------+
|i13 : R = Q/I                                                                |
|                                                                             |
|o13 = R                                                                      |
|                                                                             |
|o13 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i14 : A = koszulComplexDGA(R)                                                |
|                                                                             |
|o14 = {Ring => R                          }                                  |
|       Underlying algebra => R[T   ..T   ]                                   |
|                                1,1   1,3                                    |
|       Differential => {x, y, z}                                             |
|                                                                             |
|o14 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i15 : apply(maxDegree A + 1, i -> numgens prune homology(i,A))               |
|                                                                             |
|o15 = {1, 7, 7, 1}                                                           |
|                                                                             |
|o15 : List                                                                   |
+-----------------------------------------------------------------------------+
|i16 : HA = homologyAlgebra(A)                                                |
|Finding easy relations           :  -- used 0.0668352s (cpu); 0.065353s      |
|                                                                             |
|o16 = HA                                                                     |
|                                                                             |
|o16 : QuotientRing                                                           |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+

One can check that HA has Poincare duality since R is Gorenstein.

If your DGAlgebra has generators in even degrees, then one must specify the
options GenDegreeLimit and RelDegreeLimit.

+-----------------------------------------------------------------------------+
|i17 : R = ZZ/101[a,b,c,d]                                                    |
|                                                                             |
|o17 = R                                                                      |
|                                                                             |
|o17 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i18 : S = R/ideal{a^4,b^4,c^4,d^4}                                           |
|                                                                             |
|o18 = S                                                                      |
|                                                                             |
|o18 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i19 : A = acyclicClosure(R,EndDegree=>3)                                     |
|                                                                             |
|o19 = {Ring => R                          }                                  |
|       Underlying algebra => R[T   ..T   ]                                   |
|                                1,1   1,4                                    |
|       Differential => {a, b, c, d}                                          |
|                                                                             |
|o19 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i20 : B = A ** S                                                             |
|                                                                             |
|o20 = {Ring => S                          }                                  |
|       Underlying algebra => S[T   ..T   ]                                   |
|                                1,1   1,4                                    |
|       Differential => {a, b, c, d}                                          |
|                                                                             |
|o20 : DGAlgebra                                                              |
+-----------------------------------------------------------------------------+
|i21 : HB = homologyAlgebra(B,GenDegreeLimit=>7,RelDegreeLimit=>14)           |
|Finding easy relations           :  -- used 0.0242572s (cpu); 0.0231568s     |
|                                                                             |
|o21 = HB                                                                     |
|                                                                             |
|o21 : PolynomialRing, 4 skew commutative variable(s)                         |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+

Ways to use homologyAlgebra:
============================

  * "homologyAlgebra(DGAlgebra)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8132:0.

homologyAlgebra(...,GenDegreeLimit=>...) -- Maximum homological degree searched for homology-algebra generators
***************************************************************************************************************

  * Usage:
        homologyAlgebra(..., GenDegreeLimit => n)

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

Required when the DG algebra has generators in even degree; see
GenDegreeLimit.

See also
========

  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.
  * GenDegreeLimit -- Option to bound the homological
    degree searched for algebra generators
  * homologyAlgebra(...,RelDegreeLimit=>...)
    -- Maximum
    homological degree searched for homology-algebra relations

Functions with optional argument named GenDegreeLimit:
======================================================

  * findTrivialMasseyOperation(...,GenDegreeLimit=>...),
    --
    Maximum homological degree of generators used in the trivial Massey
    operation search
  * homologyAlgebra(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree searched for homology-algebra generators
  * isGolodHomomorphism(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree of generators used by isGolodHomomorphism
  * isHomologyAlgebraTrivial(...,GenDegreeLimit=>...),
    --
    Maximum homological degree of generators used by isHomologyAlgebraTrivial
  * torAlgebra(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree searched for Tor-algebra generators
  * "torMap(...,GenDegreeLimit=>...)" -- see torMap, -- Compute
    the map of Tor algebras associated to a RingMap.

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

  * Default value: infinity (Macaulay2Doc),
  * Function: homologyAlgebra, -- Compute the homology
    algebra of a DGAlgebra.
  * Option key: GenDegreeLimit, -- Option to bound the
    homological degree searched for algebra generators
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9624:0.

homologyAlgebra(...,RelDegreeLimit=>...) -- Maximum homological degree searched for homology-algebra relations
**************************************************************************************************************

  * Usage:
        homologyAlgebra(..., RelDegreeLimit => n)

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

Bounds the degree up to which relations are computed; see RelDegreeLimit.

See also
========

  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.
  * RelDegreeLimit -- Option to bound the homological
    degree searched for algebra relations
  * homologyAlgebra(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree searched for homology-algebra generators

Functions with optional argument named RelDegreeLimit:
======================================================

  * homologyAlgebra(...,RelDegreeLimit=>...)
    -- Maximum
    homological degree searched for homology-algebra relations
  * torAlgebra(...,RelDegreeLimit=>...)
    -- Maximum
    homological degree searched for Tor-algebra relations

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

  * Default value: infinity (Macaulay2Doc),
  * Function: homologyAlgebra, -- Compute the homology
    algebra of a DGAlgebra.
  * Option key: RelDegreeLimit, -- Option to bound the
    homological degree searched for algebra relations
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9640:0.

homologyAlgebra(...,Verbosity=>...) -- Option to control progress output from homologyAlgebra
*********************************************************************************************

  * Usage:
        homologyAlgebra(...,Verbosity=>n)

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

Larger values of n print progress messages about the generator and relation
searches carried out by homologyAlgebra.  The default
is 0 (no output).

See also
========

  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.

Functions with optional argument named Verbosity:
=================================================

  * getGenerators(...,Verbosity=>...)
    -- Option to control
    progress output from getGenerators
  * homologyAlgebra(...,Verbosity=>...)
    -- Option to control
    progress output from homologyAlgebra
  * icFracP(...,Verbosity=>...) (IntegralClosure)
    -- Prints
    out the conductor element and the number of intermediate modules it
    computed.
  * "idealizer(...,Verbosity=>...)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * integralClosure(...,Verbosity=>...) (IntegralClosure),
    --
    display a certain amount of detail about the computation
  * "isPrime(Ideal,Verbosity=>...)" -- see isPrime(Ideal) (MinimalPrimes),
    -- whether an ideal is prime
  * "makeS2(...,Verbosity=>...)" -- see makeS2 (IntegralClosure),
    -- compute the S2ification of a reduced ring
  * "decompose(Ideal,Verbosity=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,Verbosity=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "ringFromFractions(...,Verbosity=>...)" -- see ringFromFractions (IntegralClosure),
    -- find presentation for f.g. ring

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

  * Default value: 0
  * Function: homologyAlgebra, -- Compute the homology
    algebra of a DGAlgebra.
  * Option key: Verbosity (missing documentation)
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9805:0.

homologyClass -- Computes the element of the homology algebra corresponding to a cycle in a DGAlgebra.
******************************************************************************************************

  * Usage:
        h = homologyClass(A,z)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * z, a ring element (Macaulay2Doc),
  * Outputs:
      * h, a ring element (Macaulay2Doc),

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

This function computes the element in the homology algebra of a cycle in a
DGAlgebra. In order to do this, the homologyAlgebra,
is retrieved (or computed, if it hasn't been already).

+-----------------------------------------------------------------------------+
|i1 : Q = QQ[x,y,z]                                                           |
|                                                                             |
|o1 = Q                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal (x^3,y^3,z^3)                                                 |
|                                                                             |
|             3   3   3                                                       |
|o2 = ideal (x , y , z )                                                      |
|                                                                             |
|o2 : Ideal of Q                                                              |
+-----------------------------------------------------------------------------+
|i3 : R = Q/I                                                                 |
|                                                                             |
|o3 = R                                                                       |
|                                                                             |
|o3 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i4 : KR = koszulComplexDGA R                                                 |
|                                                                             |
|o4 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,3                                     |
|      Differential => {x, y, z}                                              |
|                                                                             |
|o4 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i5 : z1 = x^2*T_(1,1)                                                        |
|                                                                             |
|      2                                                                      |
|o5 = x T                                                                     |
|        1,1                                                                  |
|                                                                             |
|o5 : R[T   ..T   ]                                                           |
|        1,1   1,3                                                            |
+-----------------------------------------------------------------------------+
|i6 : z2 = y^2*T_(1,2)                                                        |
|                                                                             |
|      2                                                                      |
|o6 = y T                                                                     |
|        1,2                                                                  |
|                                                                             |
|o6 : R[T   ..T   ]                                                           |
|        1,1   1,3                                                            |
+-----------------------------------------------------------------------------+
|i7 : H = HH(KR)                                                              |
|Finding easy relations           :  -- used 0.0190911s (cpu); 0.0180955s     |
|                                                                             |
|o7 = H                                                                       |
|                                                                             |
|o7 : PolynomialRing, 3 skew commutative variable(s)                          |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i8 : homologyClass(KR,z1*z2)                                                 |
|                                                                             |
|o8 = X X                                                                     |
|      1 2                                                                    |
|                                                                             |
|o8 : H                                                                       |
+-----------------------------------------------------------------------------+

Ways to use homologyClass:
==========================

  * "homologyClass(DGAlgebra,RingElement)"
  * homologyClass(DGModule,Vector),
    -- The homology class of a cycle in a DG module

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8839:0.

homologyModule -- Compute the homology of a DGModule as a module over a DGAlgebra.
**********************************************************************************

  * Usage:
        HM = homologyModule(A,M)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * M, a module (Macaulay2Doc),
  * Outputs:
      * HM, a module (Macaulay2Doc),

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

Given a DGAlgebra A over a ring R, and an R-module M, A ** M carries the
structure of a left DG module over A.  It follows that H(A ** M) is a module
over H(A). Although DGModules have yet to be implemented as objects in
Macaulay2 in their own right, the current infrastructure (with a little extra
work) allows us to determine the module structure of this type of DG module as
a module over the homology algebra of A.

Currently, this code will only work on DGAlgebras that are finite over their
ring of definition, such as Koszul complexes.  (Truncations of) module
structures in case of non-finite DGAlgebras may be made available in a future
update.

For an example, we will compute the module structure of the Koszul homology of
the canonical module over the Koszul homology algebra.

+------------------------------------------------------------------------+
|i1 : Q = QQ[x,y,z,w]                                                    |
|                                                                        |
|o1 = Q                                                                  |
|                                                                        |
|o1 : PolynomialRing                                                     |
+------------------------------------------------------------------------+
|i2 : I = ideal (w^2, y*w+z*w, x*w, y*z+z^2, y^2+z*w, x*y+x*z, x^2+z*w)  |
|                                                                        |
|             2                         2   2                    2       |
|o2 = ideal (w , y*w + z*w, x*w, y*z + z , y  + z*w, x*y + x*z, x  + z*w)|
|                                                                        |
|o2 : Ideal of Q                                                         |
+------------------------------------------------------------------------+
|i3 : R = Q/I                                                            |
|                                                                        |
|o3 = R                                                                  |
|                                                                        |
|o3 : QuotientRing                                                       |
+------------------------------------------------------------------------+
|i4 : KR = koszulComplexDGA R                                            |
|                                                                        |
|o4 = {Ring => R                          }                              |
|      Underlying algebra => R[T   ..T   ]                               |
|                               1,1   1,4                                |
|      Differential => {x, y, z, w}                                      |
|                                                                        |
|o4 : DGAlgebra                                                          |
+------------------------------------------------------------------------+
|i5 : cxKR = toComplex KR                                                |
|                                                                        |
|      1      4      6      4      1                                     |
|o5 = R  <-- R  <-- R  <-- R  <-- R                                      |
|                                                                        |
|     0      1      2      3      4                                      |
|                                                                        |
|o5 : Complex                                                            |
+------------------------------------------------------------------------+
|i6 : HKR = HH(KR)                                                       |
| -- used 0.137845s (cpu); 0.135433s (thread); 0s (gc)                   |
|Finding easy relations           :                                      |
|o6 = HKR                                                                |
|                                                                        |
|o6 : QuotientRing                                                       |
+------------------------------------------------------------------------+

The following is the graded canonical module of R:

+--------------------------------------------------------+
|i7 : degList = first entries vars Q / degree / first    |
|                                                        |
|o7 = {1, 1, 1, 1}                                       |
|                                                        |
|o7 : List                                               |
+--------------------------------------------------------+
|i8 : M = Ext^4(Q^1/I,Q^{-(sum degList)}) ** R           |
|                                                        |
|o8 = cokernel {-2} | w x z 0   0 0  0   0 -zw 0     0  ||
|              {-2} | 0 0 w y+z 0 x  0   w 0   z2+zw 0  ||
|              {-2} | 0 0 0 0   w -z y+z x 0   0     z2 ||
|                                                        |
|                            3                           |
|o8 : R-module, quotient of R                            |
+--------------------------------------------------------+

We obtain the Koszul homology module using the following command:

+--------------------------------+
|i9 : HKM = homologyModule(KR,M);|
+--------------------------------+

One may notice the duality of HKR and HKM by considering their Hilbert series:

+-------------------------------------------------------------------------+
|i10 : hsHKR = value numerator reduceHilbert hilbertSeries HKR            |
|                                                                         |
|              2     2 4     2 3     3 5     3 4     4 6                  |
|o10 = 1 + 7T T  + 6T T  + 8T T  + 8T T  + 3T T  + 3T T                   |
|            0 1     0 1     0 1     0 1     0 1     0 1                  |
|                                                                         |
|o10 : ZZ[T ..T ]                                                         |
|          0   1                                                          |
+-------------------------------------------------------------------------+
|i11 : hsHKM = value numerator reduceHilbert hilbertSeries HKM            |
|                                                                         |
|        -2             -1     2       2     3 2    4 4                   |
|o11 = 3T   + 3T  + 8T T   + 8T T  + 6T  + 7T T  + T T                    |
|        1      0     0 1      0 1     0     0 1    0 1                   |
|                                                                         |
|o11 : ZZ[T ..T ]                                                         |
|          0   1                                                          |
+-------------------------------------------------------------------------+
|i12 : AA = ring hsHKR                                                    |
|                                                                         |
|o12 = AA                                                                 |
|                                                                         |
|o12 : PolynomialRing                                                     |
+-------------------------------------------------------------------------+
|i13 : e = numgens Q                                                      |
|                                                                         |
|o13 = 4                                                                  |
+-------------------------------------------------------------------------+
|i14 : hsHKR == T_0^e*T_1^e*sub(hsHKM, {T_0 => T_0^(-1), T_1 => T_1^(-1)})|
|                                                                         |
|o14 = true                                                               |
+-------------------------------------------------------------------------+

Ways to use homologyModule:
===========================

  * "homologyModule(DGModule)" -- see HH DGModule, -- The
    graded homology of a DG module as a module over HH(A)
  * "homologyModule(DGQuotientModule)" -- see HH DGQuotientModule,
    -- The graded homology of a DG quotient module
  * "homologyModule(DGAlgebra,Module)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9227:0.

identityDGAlgebraMap -- The identity DGAlgebraMap on a DG algebra
*****************************************************************

  * Usage:
        idA = identityDGAlgebraMap A
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Outputs:
      * idA, an instance of the type DGAlgebraMap,

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

Returns the identity self-map of A as a DGAlgebraMap.  Under the hood the
underlying RingMap A.natural -> A.natural is the identity map on every
generator (including the base-ring generators).

+-----------------------------------------------------------+
|i1 : R = QQ[x,y]/ideal(x^2,y^2)                            |
|                                                           |
|o1 = R                                                     |
|                                                           |
|o1 : QuotientRing                                          |
+-----------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                |
|                                                           |
|o2 = {Ring => R                          }                 |
|      Underlying algebra => R[T   ..T   ]                  |
|                               1,1   1,2                   |
|      Differential => {x, y}                               |
|                                                           |
|o2 : DGAlgebra                                             |
+-----------------------------------------------------------+
|i3 : idA = identityDGAlgebraMap A                          |
|                                                           |
|o3 = map (R[T   ..T   ], R[T   ..T   ], {T   , T   , x, y})|
|             1,1   1,2      1,1   1,2     1,1   1,2        |
|                                                           |
|o3 : DGAlgebraMap                                          |
+-----------------------------------------------------------+
|i4 : (idA * idA) == idA                                    |
|                                                           |
|o4 = true                                                  |
+-----------------------------------------------------------+

See also
========

  * dgAlgebraMap -- Define a DG algebra map between DG
    algebras.
  * DGAlgebraMap * DGAlgebraMap, --
    Composition of DG algebra maps

Ways to use identityDGAlgebraMap:
=================================

  * "identityDGAlgebraMap(DGAlgebra)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:580:0.

identityDGModuleMap -- The identity DGModuleMap on a DG module
**************************************************************

  * Usage:
        idM = identityDGModuleMap M
  * Inputs:
      * M, an instance of the type DGModule,
  * Outputs:
      * idM, an instance of the type DGModuleMap,

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

Returns the identity endomorphism of M as a DGModuleMap.  Its underlying
natural matrix is $\mathrm{id}_{M.natural}$ and its induced map on every
homology degree is the identity.

The shorthand id_M (mirroring the Complexes, convention
id_C for a Complex C) is an alias, and both forms compare equal to the scalar
1:

+------------------------------------------+
|i1 : R = ZZ/101[x, y] / ideal(x^2, y^2)   |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : QuotientRing                         |
+------------------------------------------+
|i2 : A = koszulComplexDGA R               |
|                                          |
|o2 = {Ring => R                          }|
|      Underlying algebra => R[T   ..T   ] |
|                               1,1   1,2  |
|      Differential => {x, y}              |
|                                          |
|o2 : DGAlgebra                            |
+------------------------------------------+
|i3 : KM = koszulComplexDGM R^1            |
|                                          |
|o3 = {Base ring => R                    } |
|      DG algebra => R[T   ..T   ]         |
|                       1,1   1,2          |
|                                       1  |
|      Natural module => (R[T   ..T   ])   |
|                            1,1   1,2     |
|      Generator degrees => {{0, 0}}       |
|      Differentials on gens => {0}        |
|                                          |
|o3 : DGModule                             |
+------------------------------------------+
|i4 : id_KM == identityDGModuleMap KM      |
|                                          |
|o4 = true                                 |
+------------------------------------------+
|i5 : id_KM == 1                           |
|                                          |
|o5 = true                                 |
+------------------------------------------+

The identity is the neutral element for composition of DG module maps. On a
semifree resolution of the residue field, the mult-by-y chain map is idempotent
under pre- and post-composition with the identity:

+--------------------------------------------------------------------------+
|i6 : Mdg = minimalSemifreeResolution(A, R^1 / ideal(x, y), EndDegree => 2)|
|                                                                          |
|o6 = {Base ring => R                                          }           |
|      DG algebra => R[T   ..T   ]                                         |
|                       1,1   1,2                                          |
|                                       3                                  |
|      Natural module => (R[T   ..T   ])                                   |
|                            1,1   1,2                                     |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}}                       |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |}            |
|                                   |     0    |  |     0    |             |
|                                   |     0    |  |     0    |             |
|                                                                          |
|o6 : DGModule                                                             |
+--------------------------------------------------------------------------+
|i7 : natGens = apply(rank Mdg.natural, i -> (Mdg.natural)_i)              |
|                                                                          |
|o7 = {| 1 |, | 0 |, | 0 |}                                                |
|      | 0 |  | 1 |  | 0 |                                                 |
|      | 0 |  | 0 |  | 1 |                                                 |
|                                                                          |
|o7 : List                                                                 |
+--------------------------------------------------------------------------+
|i8 : fy = dgModuleMap(Mdg, Mdg, apply(natGens, v -> y * v))               |
|                                                                          |
|                               3                                          |
|o8 = {Source => (R[T   ..T   ])  }                                        |
|                    1,1   1,2                                             |
|                               3                                          |
|      Target => (R[T   ..T   ])                                           |
|                    1,1   1,2                                             |
|      Natural => {0, 0} | y 0 0 |                                         |
|                 {2, 2} | 0 y 0 |                                         |
|                 {2, 2} | 0 0 y |                                         |
|                                                                          |
|o8 : DGModuleMap                                                          |
+--------------------------------------------------------------------------+
|i9 : idMdg = identityDGModuleMap Mdg                                      |
|                                                                          |
|                               3                                          |
|o9 = {Source => (R[T   ..T   ])  }                                        |
|                    1,1   1,2                                             |
|                               3                                          |
|      Target => (R[T   ..T   ])                                           |
|                    1,1   1,2                                             |
|      Natural => {0, 0} | 1 0 0 |                                         |
|                 {2, 2} | 0 1 0 |                                         |
|                 {2, 2} | 0 0 1 |                                         |
|                                                                          |
|o9 : DGModuleMap                                                          |
+--------------------------------------------------------------------------+
|i10 : idMdg * fy == fy                                                    |
|                                                                          |
|o10 = true                                                                |
+--------------------------------------------------------------------------+
|i11 : fy * idMdg == fy                                                    |
|                                                                          |
|o11 = true                                                                |
+--------------------------------------------------------------------------+
|i12 : idMdg * idMdg == idMdg                                              |
|                                                                          |
|o12 = true                                                                |
+--------------------------------------------------------------------------+

See also
========

  * dgModuleMap -- Construct a DGModuleMap from a matrix or
    from a list of image Vectors
  * zeroDGModuleMap -- The zero DGModuleMap between two
    DG modules over a common algebra

Ways to use identityDGModuleMap:
================================

  * "identityDGModuleMap(DGModule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:394:0.

isAcyclic -- Determine whether a DG algebra has no higher homology
******************************************************************

  * Usage:
        isAcyc = isAcyclic A
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Optional inputs (Macaulay2Doc),:
      * EndDegree, =>
        ..., default value -1, Option to specify the degree to finish checking
        acyclicity
  * Outputs:
      * isAcyc, a Boolean value (Macaulay2Doc), true if HH_i A =
        0 for all i > 0, and false otherwise

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

A DG algebra is acyclic (in the convention used by this package) if it has zero
homology in all positive degrees, so that A -> HH_0 A is a quasi-isomorphism.
isAcyclic checks homology degree by degree up through maxDegree A; for
unbounded DG algebras an EndDegree, option bounds the search.

The Koszul complex of a regular sequence is acyclic:

+----------------------------------+
|i1 : Q = ZZ/101[a,b,c,d]          |
|                                  |
|o1 = Q                            |
|                                  |
|o1 : PolynomialRing               |
+----------------------------------+
|i2 : I = ideal(a^4, b^4, c^4, d^4)|
|                                  |
|             4   4   4   4        |
|o2 = ideal (a , b , c , d )       |
|                                  |
|o2 : Ideal of Q                   |
+----------------------------------+
|i3 : isAcyclic(koszulComplexDGA I)|
|                                  |
|o3 = true                         |
+----------------------------------+

But the Koszul complex of a ring with nontrivial relations in homology is not:

+-------------------------------------------------------+
|i4 : R = ZZ/101[a,b,c,d] / ideal(a^4 + b^4 + c^4 + d^4)|
|                                                       |
|o4 = R                                                 |
|                                                       |
|o4 : QuotientRing                                      |
+-------------------------------------------------------+
|i5 : isAcyclic(koszulComplexDGA R)                     |
|                                                       |
|o5 = false                                             |
+-------------------------------------------------------+

An acyclic closure built to sufficient degree is acyclic in the checked range:

+-------------------------------------------------------------------+
|i6 : R = ZZ/101[a,b,c,d] / ideal(a^3, b^3, c^3, d^3)               |
|                                                                   |
|o6 = R                                                             |
|                                                                   |
|o6 : QuotientRing                                                  |
+-------------------------------------------------------------------+
|i7 : A = acyclicClosure(R, EndDegree => 3)                         |
|                                                                   |
|o7 = {Ring => R                                                   }|
|      Underlying algebra => R[T   ..T   ]                          |
|                               1,1   2,4                           |
|                                    2       2       2       2      |
|      Differential => {a, b, c, d, a T   , b T   , c T   , d T   } |
|                                      1,1     1,2     1,3     1,4  |
|                                                                   |
|o7 : DGAlgebra                                                     |
+-------------------------------------------------------------------+
|i8 : isAcyclic(A, EndDegree => 3)                                  |
|                                                                   |
|o8 = true                                                          |
+-------------------------------------------------------------------+

See also
========

  * DGAlgebra -- The class of all DGAlgebras
  * HH_ZZ DGAlgebra -- Computes the homology of a DG
    algebra as a module
  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension

Ways to use isAcyclic:
======================

  * "isAcyclic(DGAlgebra)"
  * isAcyclic(DGModule) -- Determine whether a
    DG module has vanishing positive-degree homology
  * isAcyclic(DGQuotientModule), --
    Determine whether a DG quotient module has vanishing positive-degree
    homology

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8317:0.

isAcyclic(...,EndDegree=>...) -- Option to specify the degree to finish checking acyclicity
*******************************************************************************************

  * Usage:
        isAcyclic(...,EndDegree=>n)

Functions with optional argument named EndDegree:
=================================================

  * acyclicClosure(...,EndDegree=>...)
    -- Option to specify
    the degree to stop computing the acyclic closure
  * isAcyclic(...,EndDegree=>...)
    -- Option to specify the
    degree to finish checking acyclicity
  * killCycles(...,EndDegree=>...)
    -- Last homological
    degree processed by killCycles
  * "liftToDGMap(...,EndDegree=>...)" -- see liftToDGMap, --
    Lift a ring homomorphism in degree zero to a DG algebra morphism
  * "liftToDGModuleMap(...,EndDegree=>...)" -- see liftToDGModuleMap,
    -- Lift an image of hom-degree-0 generators to a full
    DGModuleMap
  * "minimalModel(...,EndDegree=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * minimalSemifreeResolution(...,EndDegree=>...)
    -- Option
    to specify the last degree at which minimalSemifreeResolution kills cycles
  * semifreeResolution(...,EndDegree=>...)
    -- Option to
    specify the last degree at which semifreeResolution kills cycles
  * "toComplexMap(...,EndDegree=>...)" -- see toComplexMap,
    -- Construct the ComplexMap associated to a DGAlgebraMap

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

  * Default value: -1
  * Function: isAcyclic, -- Determine whether a DG algebra has
    no higher homology
  * Option key: EndDegree, -- Option to specify the last
    homological degree processed by an iterative DG construction
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9435:0.

isGolod -- Determines if a ring is Golod
****************************************

  * Usage:
        isGol = isGolod(R)
  * Inputs:
      * R, a ring (Macaulay2Doc),
  * Outputs:
      * isGol, a Boolean value (Macaulay2Doc),

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

This function determines if the Koszul complex of a ring R admits a trivial
Massey operation.  If one exists, then R is Golod.

+-----------------------------------------------+
|i1 : R = ZZ/101[a,b,c,d]/ideal{a^4+b^4+c^4+d^4}|
|                                               |
|o1 = R                                         |
|                                               |
|o1 : QuotientRing                              |
+-----------------------------------------------+
|i2 : isGolod(R)                                |
|                                               |
|o2 = true                                      |
+-----------------------------------------------+

Hypersurfaces are Golod, but

+-----------------------------------------------+
|i3 : R = ZZ/101[a,b,c,d]/ideal{a^4,b^4,c^4,d^4}|
|                                               |
|o3 = R                                         |
|                                               |
|o3 : QuotientRing                              |
+-----------------------------------------------+
|i4 : isGolod(R)                                |
|                                               |
|o4 = false                                     |
+-----------------------------------------------+

complete intersections of higher codimension are not.  Here is another example:

+---------------------------+
|i5 : Q = ZZ/101[a,b,c,d]   |
|                           |
|o5 = Q                     |
|                           |
|o5 : PolynomialRing        |
+---------------------------+
|i6 : R = Q/(ideal vars Q)^2|
|                           |
|o6 = R                     |
|                           |
|o6 : QuotientRing          |
+---------------------------+
|i7 : isGolod(R)            |
|                           |
|o7 = true                  |
+---------------------------+

The above is a (CM) ring minimal of minimal multiplicity, hence Golod.  The
next example was found by Lukas Katthan, and appears in his arXiv paper
1511.04883.  It is the first known example of an algebra that is not Golod, but
whose Koszul complex has a trivial homology product.

+-----------------------------------------------------------------------------+
|i8 : Q = ZZ/101[x_1,x_2,y_1,y_2,z,w]                                         |
|                                                                             |
|o8 = Q                                                                       |
|                                                                             |
|o8 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i9 : I = ideal {x_1*x_2^2,z^2*w,y_1*y_2^2,x_2^2*z*w,y_2^2*z^2,x_1*x_2*y_1*y_2|
|                                                                             |
|               2   2      2   2      2 2             2 2                     |
|o9 = ideal (x x , z w, y y , x z*w, y z , x x y y , x y z, x y z)            |
|             1 2        1 2   2      2     1 2 1 2   2 2    1 1              |
|                                                                             |
|o9 : Ideal of Q                                                              |
|-----------------------------------------------------------------------------|
|,x_2^2*y_2^2*z,x_1*y_1*z}                                                    |
+-----------------------------------------------------------------------------+
|i10 : R = Q/I                                                                |
|                                                                             |
|o10 = R                                                                      |
|                                                                             |
|o10 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i11 : isHomologyAlgebraTrivial koszulComplexDGA R                            |
|                                                                             |
|o11 = true                                                                   |
+-----------------------------------------------------------------------------+
|i12 : isGolod R                                                              |
|                                                                             |
|o12 = false                                                                  |
+-----------------------------------------------------------------------------+

Note that since the Koszul complex is zero in homological degree beyond the
embedding dimension, there are only finitely many Massey products that one
needs to check to verify that a ring is Golod.

Ways to use isGolod:
====================

  * "isGolod(Ring)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8361:0.

isGolodHomomorphism -- Determines if the canonical map from the ambient ring is Golod
*************************************************************************************

  * Usage:
        isGol = isGolodHomomorphism(R)
  * Inputs:
      * R, a quotient ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * GenDegreeLimit,
        => ..., default value infinity, Maximum homological
        degree of generators used by isGolodHomomorphism
      * TMOLimit,
        => ..., default value infinity, Option to cap the arity of the
        trivial Massey operation used in isGolodHomomorphism
  * Outputs:
      * isGol, a Boolean value (Macaulay2Doc),

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

This function determines if the canonical map from ambient R --> R is Golod.
It does this by computing an acyclic closure of ambient R (which is a
DGAlgebra), then tensors this with R, and determines if this DG
Algebra has a trivial Massey operation up to a certain homological degree
provided by the option GenDegreeLimit.

+-----------------------------------------------+
|i1 : R = ZZ/101[a,b,c,d]/ideal{a^4+b^4+c^4+d^4}|
|                                               |
|o1 = R                                         |
|                                               |
|o1 : QuotientRing                              |
+-----------------------------------------------+
|i2 : isGolodHomomorphism(R,GenDegreeLimit=>5)  |
|                                               |
|o2 = true                                      |
+-----------------------------------------------+

If R is a Golod ring, then ambient R $\rightarrow$ R is a Golod homomorphism.

+---------------------------------------------------------+
|i3 : Q = ZZ/101[a,b,c,d]/ideal{a^4,b^4,c^4,d^4}          |
|                                                         |
|o3 = Q                                                   |
|                                                         |
|o3 : QuotientRing                                        |
+---------------------------------------------------------+
|i4 : R = Q/ideal (a^3*b^3*c^3*d^3)                       |
|                                                         |
|o4 = R                                                   |
|                                                         |
|o4 : QuotientRing                                        |
+---------------------------------------------------------+
|i5 : isGolodHomomorphism(R,GenDegreeLimit=>5,TMOLimit=>3)|
|                                                         |
|o5 = true                                                |
+---------------------------------------------------------+

The map from Q to R is Golod by a result of Avramov and Levin; we can only find
the trivial Massey operations out to a given degree.

Ways to use isGolodHomomorphism:
================================

  * "isGolodHomomorphism(QuotientRing)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8391:0.

isGolodHomomorphism(...,GenDegreeLimit=>...) -- Maximum homological degree of generators used by isGolodHomomorphism
********************************************************************************************************************

  * Usage:
        isGolodHomomorphism(..., GenDegreeLimit => n)

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

See GenDegreeLimit.

See also
========

  * isGolodHomomorphism -- Determines if the
    canonical map from the ambient ring is Golod
  * GenDegreeLimit -- Option to bound the homological
    degree searched for algebra generators
  * TMOLimit -- Option to bound the arity of Massey operations
    searched for by findTrivialMasseyOperation

Functions with optional argument named GenDegreeLimit:
======================================================

  * findTrivialMasseyOperation(...,GenDegreeLimit=>...),
    --
    Maximum homological degree of generators used in the trivial Massey
    operation search
  * homologyAlgebra(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree searched for homology-algebra generators
  * isGolodHomomorphism(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree of generators used by isGolodHomomorphism
  * isHomologyAlgebraTrivial(...,GenDegreeLimit=>...),
    --
    Maximum homological degree of generators used by isHomologyAlgebraTrivial
  * torAlgebra(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree searched for Tor-algebra generators
  * "torMap(...,GenDegreeLimit=>...)" -- see torMap, -- Compute
    the map of Tor algebras associated to a RingMap.

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

  * Default value: infinity (Macaulay2Doc),
  * Function: isGolodHomomorphism, -- Determines if
    the canonical map from the ambient ring is Golod
  * Option key: GenDegreeLimit, -- Option to bound the
    homological degree searched for algebra generators
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9734:0.

isGolodHomomorphism(...,TMOLimit=>...) -- Option to cap the arity of the trivial Massey operation used in isGolodHomomorphism
*****************************************************************************************************************************

  * Usage:
        isGolodHomomorphism(...,TMOLimit=>n)

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

Passes through to findTrivialMasseyOperation,:
only products of up to n cycle representatives are
considered when searching for a trivial Massey operation on the Koszul
homology.  See TMOLimit.

See also
========

  * isGolodHomomorphism -- Determines if the
    canonical map from the ambient ring is Golod
  * TMOLimit -- Option to bound the arity of Massey operations
    searched for by findTrivialMasseyOperation
  * findTrivialMasseyOperation -- Finds a
    trivial Massey operation on a set of generators of H(A)

Functions with optional argument named TMOLimit:
================================================

  * findTrivialMasseyOperation(...,TMOLimit=>...)
    -- Maximum
    arity of Massey products searched for bounding
  * isGolodHomomorphism(...,TMOLimit=>...)
    -- Option to cap
    the arity of the trivial Massey operation used in isGolodHomomorphism

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

  * Default value: infinity (Macaulay2Doc),
  * Function: isGolodHomomorphism, -- Determines if
    the canonical map from the ambient ring is Golod
  * Option key: TMOLimit, -- Option to bound the arity of
    Massey operations searched for by findTrivialMasseyOperation
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9769:0.

isHomogeneous(DGAlgebra) -- Determine if the DGAlgebra respects the gradings of the ring it is defined over.
************************************************************************************************************

  * Function: isHomogeneous (Macaulay2Doc),
  * Usage:
        isHom = isHomogeneous(A)
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Outputs:
      * isHom, a Boolean value (Macaulay2Doc), Whether or not
        the DGA respects the grading

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

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[x,y,z]                                                       |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : A = freeDGAlgebra(R,{{1},{1},{1},{3}})                                  |
|                                                                             |
|o2 = {Ring => R                                }                             |
|      Underlying algebra => R[T   ..T   , T   ]                              |
|                               1,1   1,3   3,1                               |
|      Differential => null                                                   |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : setDiff(A,{x,y,z,x*T_(1,2)*T_(1,3)-y*T_(1,1)*T_(1,3)+z*T_(1,1)*T_(1,2)})|
|                                                                             |
|o3 = {Ring => R                                                      }       |
|      Underlying algebra => R[T   ..T   , T   ]                              |
|                               1,1   1,3   3,1                               |
|      Differential => {x, y, z, z*T   T    - y*T   T    + x*T   T   }        |
|                                   1,1 1,2      1,1 1,3      1,2 1,3         |
|                                                                             |
|o3 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i4 : isHomogeneous A                                                         |
|                                                                             |
|o4 = false                                                                   |
+-----------------------------------------------------------------------------+
|i5 : B = freeDGAlgebra(R,{{1,1},{1,1},{1,1},{3,3}})                          |
|                                                                             |
|o5 = {Ring => R                                }                             |
|      Underlying algebra => R[T   ..T   , T   ]                              |
|                               1,1   1,3   3,1                               |
|      Differential => null                                                   |
|                                                                             |
|o5 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i6 : setDiff(B,{x,y,z,x*T_(1,2)*T_(1,3)-y*T_(1,1)*T_(1,3)+z*T_(1,1)*T_(1,2)})|
|                                                                             |
|o6 = {Ring => R                                                      }       |
|      Underlying algebra => R[T   ..T   , T   ]                              |
|                               1,1   1,3   3,1                               |
|      Differential => {x, y, z, z*T   T    - y*T   T    + x*T   T   }        |
|                                   1,1 1,2      1,1 1,3      1,2 1,3         |
|                                                                             |
|o6 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i7 : isHomogeneous B                                                         |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+

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

  * isHomogeneous(DGAlgebra) -- Determine
    if the DGAlgebra respects the gradings of the ring it is defined over.
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1160:0.

isHomologyAlgebraTrivial -- Determines if the homology algebra of a DGAlgebra is trivial
****************************************************************************************

  * Usage:
        isTriv = isHomologyAlgebraTrivial(A)
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Optional inputs (Macaulay2Doc),:
      * GenDegreeLimit,
        => ..., default value infinity, Maximum
        homological degree of generators used by isHomologyAlgebraTrivial
  * Outputs:
      * isTriv, a Boolean value (Macaulay2Doc),

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

This function computes the homology algebra of the DGAlgebra A and determines
if the multiplication on H(A) is trivial.

+-------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c,d]/ideal{a^4,b^4,c^4,d^4}                    |
|                                                                   |
|o1 = R                                                             |
|                                                                   |
|o1 : QuotientRing                                                  |
+-------------------------------------------------------------------+
|i2 : S = R/ideal{a^3*b^3*c^3*d^3}                                  |
|                                                                   |
|o2 = S                                                             |
|                                                                   |
|o2 : QuotientRing                                                  |
+-------------------------------------------------------------------+
|i3 : A = acyclicClosure(R,EndDegree=>3)                            |
|                                                                   |
|o3 = {Ring => R                                                   }|
|      Underlying algebra => R[T   ..T   ]                          |
|                               1,1   2,4                           |
|                                    3       3       3       3      |
|      Differential => {a, b, c, d, a T   , b T   , c T   , d T   } |
|                                      1,1     1,2     1,3     1,4  |
|                                                                   |
|o3 : DGAlgebra                                                     |
+-------------------------------------------------------------------+
|i4 : B = A ** S                                                    |
|                                                                   |
|o4 = {Ring => S                                                   }|
|      Underlying algebra => S[T   ..T   ]                          |
|                               1,1   2,4                           |
|                                    3       3       3       3      |
|      Differential => {a, b, c, d, a T   , b T   , c T   , d T   } |
|                                      1,1     1,2     1,3     1,4  |
|                                                                   |
|o4 : DGAlgebra                                                     |
+-------------------------------------------------------------------+
|i5 : isHomologyAlgebraTrivial(B,GenDegreeLimit=>6)                 |
|                                                                   |
|o5 = true                                                          |
+-------------------------------------------------------------------+

The command returns true since R --> S is Golod.  Notice we also used the
option GenDegreeLimit here.

+-----------------------------------------------+
|i6 : R = ZZ/101[a,b,c,d]/ideal{a^4,b^4,c^4,d^4}|
|                                               |
|o6 = R                                         |
|                                               |
|o6 : QuotientRing                              |
+-----------------------------------------------+
|i7 : A = koszulComplexDGA(R)                   |
|                                               |
|o7 = {Ring => R                          }     |
|      Underlying algebra => R[T   ..T   ]      |
|                               1,1   1,4       |
|      Differential => {a, b, c, d}             |
|                                               |
|o7 : DGAlgebra                                 |
+-----------------------------------------------+
|i8 : isHomologyAlgebraTrivial(A)               |
|                                               |
|o8 = false                                     |
+-----------------------------------------------+

The command returns false, since R is Gorenstein, and so HA has Poincare
Duality, hence the multiplication is far from trivial.

Ways to use isHomologyAlgebraTrivial:
=====================================

  * "isHomologyAlgebraTrivial(DGAlgebra)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8274:0.

isHomologyAlgebraTrivial(...,GenDegreeLimit=>...) -- Maximum homological degree of generators used by isHomologyAlgebraTrivial
******************************************************************************************************************************

  * Usage:
        isHomologyAlgebraTrivial(..., GenDegreeLimit => n)

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

See GenDegreeLimit.

See also
========

  * isHomologyAlgebraTrivial -- Determines if
    the homology algebra of a DGAlgebra is trivial
  * GenDegreeLimit -- Option to bound the homological
    degree searched for algebra generators

Functions with optional argument named GenDegreeLimit:
======================================================

  * findTrivialMasseyOperation(...,GenDegreeLimit=>...),
    --
    Maximum homological degree of generators used in the trivial Massey
    operation search
  * homologyAlgebra(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree searched for homology-algebra generators
  * isGolodHomomorphism(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree of generators used by isGolodHomomorphism
  * isHomologyAlgebraTrivial(...,GenDegreeLimit=>...),
    --
    Maximum homological degree of generators used by isHomologyAlgebraTrivial
  * torAlgebra(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree searched for Tor-algebra generators
  * "torMap(...,GenDegreeLimit=>...)" -- see torMap, -- Compute
    the map of Tor algebras associated to a RingMap.

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

  * Default value: infinity (Macaulay2Doc),
  * Function: isHomologyAlgebraTrivial, --
    Determines if the homology algebra of a DGAlgebra is trivial
  * Option key: GenDegreeLimit, -- Option to bound the
    homological degree searched for algebra generators
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9718:0.

killCycles -- Adjoin variables to kill non-bounding cycles in the lowest positive degree
****************************************************************************************

  * Usage:
        B = killCycles A
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Optional inputs (Macaulay2Doc),:
      * EndDegree, =>
        ..., default value -1, Last homological degree processed by killCycles
      * StartDegree,
        => ..., default value 1, First homological degree from which killCycles
        begins searching for cycles
      * Variable, =>
        ..., default value null, Option to name the DG algebra generators
        adjoined by killCycles
  * Outputs:
      * B, an instance of the type DGAlgebra, a new DG
        algebra with extra generators adjoined to make every cycle in the first
        positive degree where HH_i A is nonzero into a boundary

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

This is the basic building block of Tate's acyclic closure construction. Given
a DG algebra A, killCycles locates the smallest positive homological degree i
in which HH_i A is nonzero, picks a generating set of cycles, and adjoins new
DG algebra generators in degree i+1 mapping to those cycles.  The result is a
DG algebra whose homology agrees with A below degree i and is killed in degree
i.  Iterating this procedure produces the acyclic closure.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c,d]/ideal{a^3, b^3, c^3 - d^4}                          |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o2 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,4                                     |
|      Differential => {a, b, c, d}                                           |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : A.diff                                                                  |
|                                                                             |
|o3 = map (R[T   ..T   ], R[T   ..T   ], {a, b, c, d, a, b, c, d})            |
|             1,1   1,4      1,1   1,4                                        |
|                                                                             |
|o3 : RingMap R[T   ..T   ] <-- R[T   ..T   ]                                 |
|                1,1   1,4         1,1   1,4                                  |
+-----------------------------------------------------------------------------+
|i4 : B = killCycles A                                                        |
|                                                                             |
|o4 = {Ring => R                                                      }       |
|      Underlying algebra => R[T   ..T   , T   ..T   ]                        |
|                               1,1   1,4   2,1   2,3                         |
|                                    2       2         2        3             |
|      Differential => {a, b, c, d, a T   , b T   , - c T    + d T   }        |
|                                      1,1     1,2       1,3      1,4         |
|                                                                             |
|o4 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i5 : B.diff                                                                  |
|                                                                             |
|                                                                             |
|o5 = map (R[T   ..T   , T   ..T   ], R[T   ..T   , T   ..T   ], {a, b, c, d, |
|             1,1   1,4   2,1   2,3      1,1   1,4   2,1   2,3                |
|                                                                             |
|o5 : RingMap R[T   ..T   , T   ..T   ] <-- R[T   ..T   , T   ..T   ]         |
|                1,1   1,4   2,1   2,3         1,1   1,4   2,1   2,3          |
|-----------------------------------------------------------------------------|
| 2       2         2        3                                                |
|a T   , b T   , - c T    + d T   , a, b, c, d})                              |
|   1,1     1,2       1,3      1,4                                            |
+-----------------------------------------------------------------------------+

The new generator T_(2,1) in B has differential equal to a chosen nonzero cycle
representative in homological degree 1 of A.

See also
========

  * DGAlgebra -- The class of all DGAlgebras
  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension
  * adjoinVariables -- Extend a DG algebra by a
    user-chosen list of cycles to be killed

Ways to use killCycles:
=======================

  * "killCycles(DGAlgebra)"
  * killCycles(DGModule) -- Adjoin free
    generators to kill the lowest nonvanishing homology of a DG module

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8001:0.

killCycles(...,EndDegree=>...) -- Last homological degree processed by killCycles
*********************************************************************************

  * Usage:
        killCycles(..., EndDegree => n)

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

Bounds the search depth of killCycles.  By default EndDegree
=> -1 tells killCycles, to stop after processing the first
degree with nontrivial homology.  See EndDegree.

See also
========

  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree
  * EndDegree -- Option to specify the last homological
    degree processed by an iterative DG construction
  * killCycles(...,StartDegree=>...)
    -- First homological
    degree from which killCycles begins searching for cycles

Functions with optional argument named EndDegree:
=================================================

  * acyclicClosure(...,EndDegree=>...)
    -- Option to specify
    the degree to stop computing the acyclic closure
  * isAcyclic(...,EndDegree=>...)
    -- Option to specify the
    degree to finish checking acyclicity
  * killCycles(...,EndDegree=>...)
    -- Last homological
    degree processed by killCycles
  * "liftToDGMap(...,EndDegree=>...)" -- see liftToDGMap, --
    Lift a ring homomorphism in degree zero to a DG algebra morphism
  * "liftToDGModuleMap(...,EndDegree=>...)" -- see liftToDGModuleMap,
    -- Lift an image of hom-degree-0 generators to a full
    DGModuleMap
  * "minimalModel(...,EndDegree=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * minimalSemifreeResolution(...,EndDegree=>...)
    -- Option
    to specify the last degree at which minimalSemifreeResolution kills cycles
  * semifreeResolution(...,EndDegree=>...)
    -- Option to
    specify the last degree at which semifreeResolution kills cycles
  * "toComplexMap(...,EndDegree=>...)" -- see toComplexMap,
    -- Construct the ComplexMap associated to a DGAlgebraMap

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

  * Default value: -1
  * Function: killCycles, -- Adjoin variables to kill
    non-bounding cycles in the lowest positive degree
  * Option key: EndDegree, -- Option to specify the last
    homological degree processed by an iterative DG construction
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9541:0.

killCycles(...,StartDegree=>...) -- First homological degree from which killCycles begins searching for cycles
**************************************************************************************************************

  * Usage:
        killCycles(..., StartDegree => n)

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

See killCycles, searches upward from StartDegree for the first
degree containing a non-bounding cycle, then adjoins generators to kill that
cycle.  See StartDegree.

See also
========

  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree
  * StartDegree -- Option to specify the first homological
    degree processed by an iterative DG construction
  * killCycles(...,EndDegree=>...)
    -- Last homological
    degree processed by killCycles

Functions with optional argument named StartDegree:
===================================================

  * acyclicClosure(...,StartDegree=>...)
    -- Option to
    specify the degree to start computing the acyclic closure.
  * getGenerators(...,StartDegree=>...)
    -- First homological
    degree in which to search for new algebra generators
  * killCycles(...,StartDegree=>...)
    -- First homological
    degree from which killCycles begins searching for cycles
  * "minimalModel(...,StartDegree=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * minimalSemifreeResolution(...,StartDegree=>...),
    --
    Option to specify the degree at which minimalSemifreeResolution starts
    killing cycles
  * semifreeResolution(...,StartDegree=>...)
    -- Option to
    specify the degree at which semifreeResolution starts killing cycles

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

  * Default value: 1
  * Function: killCycles, -- Adjoin variables to kill
    non-bounding cycles in the lowest positive degree
  * Option key: StartDegree, -- Option to specify the first
    homological degree processed by an iterative DG construction
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9523:0.

killCycles(...,Variable=>...) -- Option to name the DG algebra generators adjoined by killCycles
************************************************************************************************

  * Usage:
        killCycles(..., Variable => "T")

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

See killCycles, adjoins new DG generators that become boundaries
of previously non-bounding cycles.  The Variable option specifies the base name
used for these new generators, so that subsequent calls produce readable and
non-colliding names.

See also
========

  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree
  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension

Functions with optional argument named Variable:
================================================

  * acyclicClosure(...,Variable=>...)
    -- Option to name the
    DG algebra generators adjoined during acyclic closure
  * adjoinVariables(...,Variable=>...)
    -- Option to name the
    DG algebra generators adjoined by adjoinVariables
  * "freeDGAlgebra(...,Variable=>...)" -- see freeDGAlgebra,
    -- Construct a free DG algebra with given generator degrees
  * "GF(...,Variable=>...)" -- see GF (Macaulay2Doc), -- make a finite
    field
  * "Grassmannian(...,Variable=>...)" -- see Grassmannian (Macaulay2Doc),
    -- compute the ideal of the Grassmannian of
    linear subspaces of a vector space
  * idealizer(...,Variable=>...) (IntegralClosure)
    -- Sets
    the name of the indexed variables introduced in computing the endomorphism
    ring Hom(J,J).
  * integralClosure(...,Variable=>...) (IntegralClosure),
    --
    set the base letter for the indexed variables introduced while computing
    the integral closure
  * killCycles(...,Variable=>...)
    -- Option to name the DG
    algebra generators adjoined by killCycles
  * "koszulComplexDGA(...,Variable=>...)" -- see koszulComplexDGA,
    -- The Koszul complex on the variables of a ring, as a DG
    algebra
  * makeS2(...,Variable=>...) (IntegralClosure)
    -- Sets the
    name of the indexed variables introduced in computing the S2-ification.
  * "minimalModel(...,Variable=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * normalCone(Ideal,RingElement,Variable=>...) (missing documentation)
  * normalCone(Ideal,Variable=>...) (missing documentation)
  * "ringFromFractions(...,Variable=>...)" -- see ringFromFractions (IntegralClosure),
    -- find presentation for f.g. ring
  * "Schubert(...,Variable=>...)" -- see Schubert (Macaulay2Doc),
    -- compute the Plücker ideal of a Schubert variety

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

  * Default value: null
  * Function: killCycles, -- Adjoin variables to kill
    non-bounding cycles in the lowest positive degree
  * Option key: Variable (Macaulay2Doc), -- an optional argument
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9559:0.

koszulComplexDGA -- The Koszul complex on the variables of a ring, as a DG algebra
**********************************************************************************

  * Usage:
        A = koszulComplexDGA R
        A = koszulComplexDGA(R, Variable => "S")
  * Inputs:
      * R, a ring (Macaulay2Doc), A polynomial ring or quotient of
        one; the Koszul complex is built on gens R.
  * Optional inputs (Macaulay2Doc),:
      * Variable => a string (Macaulay2Doc), default value "T",
        Base name for the Koszul generators.  Defaults to "T". Both String and
        Symbol values are accepted.
  * Outputs:
      * A, an instance of the type DGAlgebra, The Koszul
        complex on gens R equipped with the structure of a DG algebra over R.

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

Given a ring R with n = numgens R generators x_1, ..., x_n, the returned DG
algebra has underlying graded-commutative polynomial ring R[T_(1,1), ...,
T_(1,n)] on n exterior (odd, square-zero) generators in hom-degree 1, with
differential d(T_(1,i)) = x_i extended by the Leibniz rule.  In the R-module
direction, the complex is identical to the classical Koszul complex
K_\bullet(x_1, ..., x_n; R).

Variable naming convention.  Generators are named T_(i, j), where i is the
homological degree (here always 1) and j is a 1-indexed counter among
generators at that hom-degree.  Pass Variable => "S" to use base name S
instead.

+-----------------------------------------------+
|i1 : R = ZZ/101[a, b, c] / ideal(a^3, b^3, c^3)|
|                                               |
|o1 = R                                         |
|                                               |
|o1 : QuotientRing                              |
+-----------------------------------------------+
|i2 : A = koszulComplexDGA R                    |
|                                               |
|o2 = {Ring => R                          }     |
|      Underlying algebra => R[T   ..T   ]      |
|                               1,1   1,3       |
|      Differential => {a, b, c}                |
|                                               |
|o2 : DGAlgebra                                 |
+-----------------------------------------------+
|i3 : gens A.natural                            |
|                                               |
|o3 = {T   , T   , T   }                        |
|       1,1   1,2   1,3                         |
|                                               |
|o3 : List                                      |
+-----------------------------------------------+
|i4 : flatten entries matrix A.diff             |
|                                               |
|o4 = {a, b, c, a, b, c}                        |
|                                               |
|o4 : List                                      |
+-----------------------------------------------+

Converting to a Complex (Complexes), gives the ordinary Koszul
complex on the variables (up to a choice of monomial order on the exterior
product); taking homology recovers the classical Koszul homology:

+-------------------------------------------------------------+
|i5 : complexA = toComplex A                                  |
|                                                             |
|      1      3      3      1                                 |
|o5 = R  <-- R  <-- R  <-- R                                  |
|                                                             |
|     0      1      2      3                                  |
|                                                             |
|o5 : Complex                                                 |
+-------------------------------------------------------------+
|i6 : complexA.dd_1                                           |
|                                                             |
|o6 = | a b c |                                               |
|                                                             |
|             1      3                                        |
|o6 : Matrix R  <-- R                                         |
+-------------------------------------------------------------+
|i7 : ranks = apply(4, i -> numgens prune HH_i complexA)      |
|                                                             |
|o7 = {1, 3, 3, 1}                                            |
|                                                             |
|o7 : List                                                    |
+-------------------------------------------------------------+
|i8 : ranks == apply(4, i -> numgens prune HH_i koszul vars R)|
|                                                             |
|o8 = true                                                    |
+-------------------------------------------------------------+

The homology can be computed directly from A via HH_ZZ DGAlgebra,
or as an algebra via homologyAlgebra.

To rename the Koszul generators, pass the Variable option:

+-----------------------------------------------+
|i9 : S = ZZ/101[a, b]                          |
|                                               |
|o9 = S                                         |
|                                               |
|o9 : PolynomialRing                            |
+-----------------------------------------------+
|i10 : AS = koszulComplexDGA(S, Variable => "U")|
|                                               |
|o10 = {Ring => S                          }    |
|       Underlying algebra => S[U   ..U   ]     |
|                                1,1   1,2      |
|       Differential => {a, b}                  |
|                                               |
|o10 : DGAlgebra                                |
+-----------------------------------------------+
|i11 : gens AS.natural                          |
|                                               |
|o11 = {U   , U   }                             |
|        1,1   1,2                              |
|                                               |
|o11 : List                                     |
+-----------------------------------------------+

Caveat
======

The Koszul complex is built on all elements of gens R, not on a minimal
generating set of a possibly non-irrelevant ideal. To build a Koszul complex on
a specific sequence of ring elements, use koszulComplexDGA(List),;
for a full generating set of an ideal, use
koszulComplexDGA(Ideal).  Also, see toComplex,
uses a different monomial order than the koszul (Macaulay2Doc),
command, so individual differentials may differ by a
basis permutation even though the complexes are isomorphic.

See also
========

  * koszulComplexDGA(Ideal) -- The Koszul
    complex on the generators of an ideal, as a DG algebra
  * koszulComplexDGA(List) -- The Koszul
    complex on a list of ring elements, as a DG algebra
  * freeDGAlgebra -- Construct a free DG algebra with
    given generator degrees
  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension
  * koszulComplexDGM -- The Koszul complex of a module
    as a DG module
  * HH_ZZ DGAlgebra -- Computes the homology of a DG
    algebra as a module
  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.

Ways to use koszulComplexDGA:
=============================

  * "koszulComplexDGA(Ring)"
  * koszulComplexDGA(Ideal) -- The Koszul
    complex on the generators of an ideal, as a DG algebra
  * koszulComplexDGA(List) -- The Koszul
    complex on a list of ring elements, as a DG algebra

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:931:0.

koszulComplexDGA(Ideal) -- The Koszul complex on the generators of an ideal, as a DG algebra
********************************************************************************************

  * Function: koszulComplexDGA,
  * Usage:
        A = koszulComplexDGA I
  * Inputs:
      * I, an ideal (Macaulay2Doc), An ideal of a ring R.
  * Optional inputs (Macaulay2Doc),:
      * Variable, => ..., default value "T", The Koszul
        complex on the variables of a ring, as a DG algebra
  * Outputs:
      * A, an instance of the type DGAlgebra, The Koszul
        complex over R on the chosen generators of I.

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

Given generators f_1, ..., f_r of I, the output is a DG algebra over R whose
underlying graded algebra is R[T_(1,1), ..., T_(1,r)] on r exterior generators
in hom-degree 1, with differential d(T_(1,i)) = f_i extended by the Leibniz
rule.  The variable naming convention and Variable option mirror
koszulComplexDGA(Ring).

+----------------------------------------------+
|i1 : R = ZZ/101[a, b, c]                      |
|                                              |
|o1 = R                                        |
|                                              |
|o1 : PolynomialRing                           |
+----------------------------------------------+
|i2 : I = ideal(a^3, b^3, c^3, a^2 * b^2 * c^2)|
|                                              |
|             3   3   3   2 2 2                |
|o2 = ideal (a , b , c , a b c )               |
|                                              |
|o2 : Ideal of R                               |
+----------------------------------------------+
|i3 : A = koszulComplexDGA I                   |
|                                              |
|o3 = {Ring => R                           }   |
|      Underlying algebra => R[T   ..T   ]     |
|                               1,1   1,4      |
|                        3   3   3   2 2 2     |
|      Differential => {a , b , c , a b c }    |
|                                              |
|o3 : DGAlgebra                                |
+----------------------------------------------+
|i4 : gens A.natural                           |
|                                              |
|o4 = {T   , T   , T   , T   }                 |
|       1,1   1,2   1,3   1,4                  |
|                                              |
|o4 : List                                     |
+----------------------------------------------+
|i5 : flatten entries matrix A.diff            |
|                                              |
|       3   3   3   2 2 2                      |
|o5 = {a , b , c , a b c , a, b, c}            |
|                                              |
|o5 : List                                     |
+----------------------------------------------+

The resulting complex coincides with koszul (Macaulay2Doc),
applied to gens I, up to monomial order:

+-------------------------------------------------------------+
|i6 : complexA = toComplex A                                  |
|                                                             |
|      1      4      6      4      1                          |
|o6 = R  <-- R  <-- R  <-- R  <-- R                           |
|                                                             |
|     0      1      2      3      4                           |
|                                                             |
|o6 : Complex                                                 |
+-------------------------------------------------------------+
|i7 : ranks = apply(5, i -> numgens prune HH_i complexA)      |
|                                                             |
|o7 = {1, 3, 0, 0, 0}                                         |
|                                                             |
|o7 : List                                                    |
+-------------------------------------------------------------+
|i8 : ranks == apply(5, i -> numgens prune HH_i koszul gens I)|
|                                                             |
|o8 = true                                                    |
+-------------------------------------------------------------+

In particular, I contains the redundant generator a^2 b^2 c^2 (it is in (a^3,
b^3, c^3)), so the Koszul complex is not exact at H_1; nonzero higher Koszul
homology encodes the relations and syzygies between the chosen generators.

See also
========

  * koszulComplexDGA(Ring) -- The Koszul complex on
    the variables of a ring, as a DG algebra
  * koszulComplexDGA(List) -- The Koszul
    complex on a list of ring elements, as a DG algebra
  * HH_ZZ DGAlgebra -- Computes the homology of a DG
    algebra as a module

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

  * koszulComplexDGA(Ideal) -- The Koszul
    complex on the generators of an ideal, as a DG algebra
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:978:0.

koszulComplexDGA(List) -- The Koszul complex on a list of ring elements, as a DG algebra
****************************************************************************************

  * Function: koszulComplexDGA,
  * Usage:
        A = koszulComplexDGA diffList
  * Inputs:
      * diffList, a list (Macaulay2Doc), A nonempty list of
        RingElement (Macaulay2Doc), s, all lying in a common ring
        R.  These become the images of the Koszul generators under the
        differential.
  * Optional inputs (Macaulay2Doc),:
      * Variable, => ..., default value "T", The Koszul
        complex on the variables of a ring, as a DG algebra
  * Outputs:
      * A, an instance of the type DGAlgebra, The Koszul
        complex over R on the sequence diffList.

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

This is the lowest-level form: the generators of I or R are replaced by an
arbitrary user-supplied list of ring elements.  Useful for building a Koszul
complex on a partial regular sequence or on arbitrary elements that may not
generate an ideal of interest.  The variable naming convention follows
koszulComplexDGA(Ring),: generators are named T_(1, j) with j
= 1, ..., #diffList.

+--------------------------------------------------+
|i1 : R = ZZ/101[x, y, z]                          |
|                                                  |
|o1 = R                                            |
|                                                  |
|o1 : PolynomialRing                               |
+--------------------------------------------------+
|i2 : A = koszulComplexDGA({x^2, y*z})             |
|                                                  |
|o2 = {Ring => R                          }        |
|      Underlying algebra => R[T   ..T   ]         |
|                               1,1   1,2          |
|                        2                         |
|      Differential => {x , y*z}                   |
|                                                  |
|o2 : DGAlgebra                                    |
+--------------------------------------------------+
|i3 : gens A.natural                               |
|                                                  |
|o3 = {T   , T   }                                 |
|       1,1   1,2                                  |
|                                                  |
|o3 : List                                         |
+--------------------------------------------------+
|i4 : flatten entries matrix A.diff                |
|                                                  |
|       2                                          |
|o4 = {x , y*z, x, y, z}                           |
|                                                  |
|o4 : List                                         |
+--------------------------------------------------+
|i5 : apply(3, i -> numgens prune HH_i toComplex A)|
|                                                  |
|o5 = {1, 0, 0}                                    |
|                                                  |
|o5 : List                                         |
+--------------------------------------------------+

Here the sequence (x^2, y z) is regular in ZZ/101[x, y, z], so the Koszul
complex is acyclic in positive homology and H_0 is the quotient R/(x^2, y z)
(of dimension 1 as an R-module).

See also
========

  * koszulComplexDGA(Ring) -- The Koszul complex on
    the variables of a ring, as a DG algebra
  * koszulComplexDGA(Ideal) -- The Koszul
    complex on the generators of an ideal, as a DG algebra

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

  * koszulComplexDGA(List) -- The Koszul
    complex on a list of ring elements, as a DG algebra
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1018:0.

liftToDGMap -- Lift a ring homomorphism in degree zero to a DG algebra morphism
*******************************************************************************

  * Usage:
        phiTilde = liftToDGMap(B,A,phi)
  * Inputs:
      * B, an instance of the type DGAlgebra, Target
      * A, an instance of the type DGAlgebra, Source
      * phi, a ring map (Macaulay2Doc), Map from A in degree
        zero to B in degree zero
  * Optional inputs (Macaulay2Doc),:
      * EndDegree => ..., default value -1
  * Outputs:
      * phiTilde, an instance of the type DGAlgebraMap,
        DGAlgebraMap lifting phi to a map of DGAlgebras.

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

In order for phiTilde to be defined, phi of the image of the differential of A
in degree 1 must lie in the image of the differential of B in degree 1.  At
present, this condition is not checked.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c]/ideal{a^3,b^3,c^3}                                    |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : S = R/ideal{a^2*b^2*c^2}                                                |
|                                                                             |
|o2 = S                                                                       |
|                                                                             |
|o2 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i3 : f = map(S,R)                                                            |
|                                                                             |
|o3 = map (S, R, {a, b, c})                                                   |
|                                                                             |
|o3 : RingMap S <-- R                                                         |
+-----------------------------------------------------------------------------+
|i4 : A = acyclicClosure(R,EndDegree=>3)                                      |
|                                                                             |
|o4 = {Ring => R                                        }                     |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   2,3                                     |
|                                 2       2       2                           |
|      Differential => {a, b, c, a T   , b T   , c T   }                      |
|                                   1,1     1,2     1,3                       |
|                                                                             |
|o4 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i5 : B = acyclicClosure(S,EndDegree=>3)                                      |
|                                                                             |
|o5 = {Ring => S                                                              |
|      Underlying algebra => S[T   ..T   , T   ..T   , T   ..T   , T   ..T   ]|
|                               1,1   1,3   2,1   2,4   3,1   3,3   4,1   4,6 |
|                                 2       2       2         2 2       2 2     |
|      Differential => {a, b, c, a T   , b T   , c T   , a*b c T   , b c T   ,|
|                                   1,1     1,2     1,3         1,1       2,1 |
|                                                                             |
|o5 : DGAlgebra                                                               |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|  2 2        2 2       2 2            2 2           2 2            2         |
|-a b T   , -a c T   , b c T   T   , -a c T   T   , b c T   T   , -a T   T   ,|
|      2,3        2,2       1,3 2,1        1,3 2,2       1,2 2,1      1,1 2,4 |
|-----------------------------------------------------------------------------|
|                       }                                                     |
|                                                                             |
|                                                                             |
| 2           2                                                               |
|c T   T   , b T   T   }                                                      |
|   1,3 2,4     1,2 2,4                                                       |
+-----------------------------------------------------------------------------+
|i6 : phi = liftToDGMap(B,A,f)                                                |
|                                                                             |
|o6 = map (S[T   ..T   , T   ..T   , T   ..T   , T   ..T   ], R[T   ..T   ],  |
|             1,1   1,3   2,1   2,4   3,1   3,3   4,1   4,6      1,1   2,3    |
|                                                                             |
|o6 : DGAlgebraMap                                                            |
|-----------------------------------------------------------------------------|
|{T   , T   , T   , T   , T   , T   , a, b, c})                               |
|  1,1   1,2   1,3   2,1   2,2   2,3                                          |
+-----------------------------------------------------------------------------+
|i7 : toComplexMap(phi,EndDegree=>3)                                          |
|                                                                             |
|                                         1                                   |
|o7 = 0 : cokernel | a2b2c2 | <--------- R  : 0                               |
|                                | 1 |                                        |
|                                                                             |
|                                                                   3         |
|     1 : cokernel {1} | a2b2c2 0      0      | <----------------- R  : 1     |
|                  {1} | 0      a2b2c2 0      |    {1} | 1 0 0 |              |
|                  {1} | 0      0      a2b2c2 |    {1} | 0 1 0 |              |
|                                                  {1} | 0 0 1 |              |
|                                                                             |
|                                                                             |
|     2 : cokernel {2} | a2b2c2 0      0      0      0      0      0          |
|                  {2} | 0      a2b2c2 0      0      0      0      0          |
|                  {2} | 0      0      a2b2c2 0      0      0      0          |
|                  {3} | 0      0      0      a2b2c2 0      0      0          |
|                  {3} | 0      0      0      0      a2b2c2 0      0          |
|                  {3} | 0      0      0      0      0      a2b2c2 0          |
|                  {6} | 0      0      0      0      0      0      a2b2c2     |
|                                                                             |
|                                                                             |
|                                                                             |
|     3 : cokernel {3} | a2b2c2 0      0      0      0      0      0          |
|                  {4} | 0      a2b2c2 0      0      0      0      0          |
|                  {4} | 0      0      a2b2c2 0      0      0      0          |
|                  {4} | 0      0      0      a2b2c2 0      0      0          |
|                  {4} | 0      0      0      0      a2b2c2 0      0          |
|                  {4} | 0      0      0      0      0      a2b2c2 0          |
|                  {4} | 0      0      0      0      0      0      a2b2c2     |
|                  {4} | 0      0      0      0      0      0      0          |
|                  {4} | 0      0      0      0      0      0      0          |
|                  {4} | 0      0      0      0      0      0      0          |
|                  {7} | 0      0      0      0      0      0      0          |
|                  {7} | 0      0      0      0      0      0      0          |
|                  {7} | 0      0      0      0      0      0      0          |
|                  {7} | 0      0      0      0      0      0      0          |
|                  {7} | 0      0      0      0      0      0      0          |
|                  {7} | 0      0      0      0      0      0      0          |
|                                                                             |
|                                                                             |
|o7 : ComplexMap                                                              |
|-----------------------------------------------------------------------------|
|                            6                                                |
|| <----------------------- R  : 2                                            |
||    {2} | 1 0 0 0 0 0 |                                                     |
||    {2} | 0 1 0 0 0 0 |                                                     |
||    {2} | 0 0 1 0 0 0 |                                                     |
||    {3} | 0 0 0 1 0 0 |                                                     |
||    {3} | 0 0 0 0 1 0 |                                                     |
||    {3} | 0 0 0 0 0 1 |                                                     |
|     {6} | 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      |             |
|a2b2c2 0      0      0      0      0      0      0      0      |             |
|0      a2b2c2 0      0      0      0      0      0      0      |             |
|0      0      a2b2c2 0      0      0      0      0      0      |             |
|0      0      0      a2b2c2 0      0      0      0      0      |             |
|0      0      0      0      a2b2c2 0      0      0      0      |             |
|0      0      0      0      0      a2b2c2 0      0      0      |             |
|0      0      0      0      0      0      a2b2c2 0      0      |             |
|0      0      0      0      0      0      0      a2b2c2 0      |             |
|0      0      0      0      0      0      0      0      a2b2c2 |             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                  10                                         |
|<------------------------------- R   : 3                                     |
|   {3} | 1 0 0 0 0 0 0 0 0 0 |                                               |
|   {4} | 0 1 0 0 0 0 0 0 0 0 |                                               |
|   {4} | 0 0 1 0 0 0 0 0 0 0 |                                               |
|   {4} | 0 0 0 1 0 0 0 0 0 0 |                                               |
|   {4} | 0 0 0 0 1 0 0 0 0 0 |                                               |
|   {4} | 0 0 0 0 0 1 0 0 0 0 |                                               |
|   {4} | 0 0 0 0 0 0 1 0 0 0 |                                               |
|   {4} | 0 0 0 0 0 0 0 1 0 0 |                                               |
|   {4} | 0 0 0 0 0 0 0 0 1 0 |                                               |
|   {4} | 0 0 0 0 0 0 0 0 0 1 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
+-----------------------------------------------------------------------------+

Ways to use liftToDGMap:
========================

  * "liftToDGMap(DGAlgebra,DGAlgebra,RingMap)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9093:0.

liftToDGModuleMap -- Lift an image of hom-degree-0 generators to a full DGModuleMap
***********************************************************************************

  * Usage:
        f = liftToDGModuleMap(N, M, h0)
  * Inputs:
      * N, an instance of the type DGModule, The target
        DGModule.  Must be acyclic in positive hom-degrees up to EndDegree so
        that lifts exist.
      * M, an instance of the type DGModule, The source
        DGModule.  Must be semifree (M.natural a free module).
      * h0, A Matrix with one column per hom-degree-0 generator of M and (rank
        N.natural)-many rows whose entries lie in A.natural, or a List of
        Vectors (in N.natural), or a single Vector when M has exactly one
        hom-degree-0 generator.
  * Optional inputs (Macaulay2Doc),:
      * EndDegree => ..., default value -1
  * Outputs:
      * f, an instance of the type DGModuleMap,

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

Starting from the supplied hom-degree-0 assignment, the routine inductively
constructs images for each M-generator of hom-degree $d \geq 1$ by solving
$d_N(x) = f(d_M(e))$ in N.natural at hom-degree $d$.  Existence of a lift at
every step is what requires N to be acyclic.  The lift is not unique in
general: different choices of preimage at each step produce chain-homotopic
lifts.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y]/ideal(x^2,y^2)                                              |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                                  |
|                                                                             |
|o2 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,2                                     |
|      Differential => {x, y}                                                 |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : Mmin = minimalSemifreeResolution(A, R^1 / ideal(x, y), EndDegree => 2)  |
|                                                                             |
|o3 = {Base ring => R                                          }              |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       3                                     |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {2, 2}, {2, 2}}                          |
|      Differentials on gens => {0, | xT_(1,1) |, | yT_(1,2) |}               |
|                                   |     0    |  |     0    |                |
|                                   |     0    |  |     0    |                |
|                                                                             |
|o3 : DGModule                                                                |
+-----------------------------------------------------------------------------+
|i4 : Mnon = semifreeResolution(A, R^1 / ideal(x, y), EndDegree => 2)         |
|                                                                             |
|o4 = {Base ring => R                                                         |
|      DG algebra => R[T   ..T   ]                                            |
|                       1,1   1,2                                             |
|                                       7                                     |
|      Natural module => (R[T   ..T   ])                                      |
|                            1,1   1,2                                        |
|      Generator degrees => {{0, 0}, {1, 1}, {1, 1}, {2, 1}, {2, 1}, {2, 2}, {|
|      Differentials on gens => {0, | x |, | y |, | -T_(1,1) |, | -T_(1,2) |, |
|                                   | 0 |  | 0 |  |     1    |  |     0    |  |
|                                   | 0 |  | 0 |  |     0    |  |     1    |  |
|                                   | 0 |  | 0 |  |     0    |  |     0    |  |
|                                   | 0 |  | 0 |  |     0    |  |     0    |  |
|                                   | 0 |  | 0 |  |     0    |  |     0    |  |
|                                   | 0 |  | 0 |  |     0    |  |     0    |  |
|                                                                             |
|o4 : DGModule                                                                |
|-----------------------------------------------------------------------------|
|                           }                                                 |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|2, 2}}                                                                       |
|| xT_(1,1) |, | yT_(1,2) |}                                                  |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
||     0    |  |     0    |                                                   |
+-----------------------------------------------------------------------------+
|i5 : quism = liftToDGModuleMap(Mnon, Mmin, {(Mnon.natural)_0}, EndDegree =>  |
|                                                                             |
|                               3                                             |
|o5 = {Source => (R[T   ..T   ])  }                                           |
|                    1,1   1,2                                                |
|                               7                                             |
|      Target => (R[T   ..T   ])                                              |
|                    1,1   1,2                                                |
|      Natural => {0, 0} | 1 0 0 |                                            |
|                 {1, 1} | 0 0 0 |                                            |
|                 {1, 1} | 0 0 0 |                                            |
|                 {2, 1} | 0 0 0 |                                            |
|                 {2, 1} | 0 0 0 |                                            |
|                 {2, 2} | 0 1 0 |                                            |
|                 {2, 2} | 0 0 1 |                                            |
|                                                                             |
|o5 : DGModuleMap                                                             |
|-----------------------------------------------------------------------------|
|2)                                                                           |
+-----------------------------------------------------------------------------+
|i6 : isWellDefined quism                                                     |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * dgModuleMap -- Construct a DGModuleMap from a matrix or
    from a list of image Vectors
  * identityDGModuleMap -- The identity DGModuleMap
    on a DG module
  * Basic operations on DG Module Maps
    -- Outlines some basic operations on DGModuleMaps

Ways to use liftToDGModuleMap:
==============================

  * "liftToDGModuleMap(DGModule,DGModule,List)"
  * "liftToDGModuleMap(DGModule,DGModule,Matrix)"
  * "liftToDGModuleMap(DGModule,DGModule,Vector)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:481:0.

masseyTripleProduct -- Computes the Massey triple product of a set of cycles or homology classes
************************************************************************************************

  * Usage:
        h = masseyTripleProduct(A,h1,h2,h3)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * h1, a ring element (Macaulay2Doc),
      * h2, a ring element (Macaulay2Doc),
      * h3, a ring element (Macaulay2Doc),
  * Outputs:
      * h, a ring element (Macaulay2Doc), The return value
        is either the homology class of the Massey triple product defined by
        the inputs or a cycle representing the homology class.

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

These functions compute the Massey triple product of either three homology
classes or three cycles that represent nonzero homology classes for which the
Massey triple product is defined.

For an example, we return to an example due to Lukas Katthan which was
discussed in isGolod. First, we define the algebra:

+-----------------------------------------------------------------------------+
|i1 : Q = QQ[x_1,x_2,y_1,y_2,z]                                               |
|                                                                             |
|o1 = Q                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal (x_1*x_2^2,y_1*y_2^2,z^3,x_1*x_2*y_1*y_2,y_2^2*z^2,x_2^2*z^2,x|
|                                                                             |
|               2     2   3             2 2   2 2          2 2                |
|o2 = ideal (x x , y y , z , x x y y , y z , x z , x y z, x y z)              |
|             1 2   1 2       1 2 1 2   2     2     1 1    2 2                |
|                                                                             |
|o2 : Ideal of Q                                                              |
|-----------------------------------------------------------------------------|
|_1*y_1*z,x_2^2*y_2^2*z)                                                      |
+-----------------------------------------------------------------------------+
|i3 : R = Q/I                                                                 |
|                                                                             |
|o3 = R                                                                       |
|                                                                             |
|o3 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i4 : KR = koszulComplexDGA R                                                 |
|                                                                             |
|o4 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,5                                     |
|      Differential => {x , x , y , y , z}                                    |
|                        1   2   1   2                                        |
|                                                                             |
|o4 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+

The following are cycles:

+-----------------------+
|i5 : z1 = z^2*T_(1,5)  |
|                       |
|      2                |
|o5 = z T               |
|        1,5            |
|                       |
|o5 : R[T   ..T   ]     |
|        1,1   1,5      |
+-----------------------+
|i6 : z2 = y_2^2*T_(1,3)|
|                       |
|      2                |
|o6 = y T               |
|      2 1,3            |
|                       |
|o6 : R[T   ..T   ]     |
|        1,1   1,5      |
+-----------------------+
|i7 : z3 = x_2^2*T_(1,1)|
|                       |
|      2                |
|o7 = x T               |
|      2 1,1            |
|                       |
|o7 : R[T   ..T   ]     |
|        1,1   1,5      |
+-----------------------+

and z1*z2, z2*z3 vanish in homology:

+------------------------------------------------------+
|i8 : (lifted12,lift12) = getBoundaryPreimage(KR,z1*z2)|
|                                                      |
|o8 = (true, 0)                                        |
|                                                      |
|o8 : Sequence                                         |
+------------------------------------------------------+
|i9 : (lifted23,lift23) = getBoundaryPreimage(KR,z2*z3)|
|                                                      |
|               2                                      |
|o9 = (true, x y T   T   T    - x x y T   T   T   )    |
|             2 2 1,1 1,2 1,3    1 2 2 1,2 1,3 1,4     |
|                                                      |
|o9 : Sequence                                         |
+------------------------------------------------------+

Note that the first return value of getBoundaryPreimage,
indicates that the inputs are indeed boundaries, and the
second value is the lift of the boundary along the differential.

Given cycles z1,z2,z3 such that z1*z2 and z2*z3 are boundaries, the Massey
triple product of the homology classes represented by z1,z2 and z3 is the
homology class of lift12*z3 + z1*lift23.  To see this, we compute and check:

+-----------------------------------------------------------------------------+
|i10 : z123 = masseyTripleProduct(KR,z1,z2,z3)                                |
|Finding easy relations           :  -- used 0.903088s (cpu); 0.825745s       |
|                                                                             |
|             2                                                               |
|o10 = x x y z T   T   T   T                                                  |
|       1 2 2   1,2 1,3 1,4 1,5                                               |
|                                                                             |
|o10 : R[T   ..T   ]                                                          |
|         1,1   1,5                                                           |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i11 : z123 == lift12*z3 + z1*lift23                                          |
|                                                                             |
|o11 = true                                                                   |
+-----------------------------------------------------------------------------+

One may also compute Massey triple products directly on elements of the
homology algebra itself, as is seen with the command masseyTripleProduct:

+---------------------------------------------+
|i12 : H = HH(KR)                             |
|                                             |
|o12 = H                                      |
|                                             |
|o12 : QuotientRing                           |
+---------------------------------------------+
|i13 : h1 = homologyClass(KR,z1)              |
|                                             |
|o13 = X                                      |
|       4                                     |
|                                             |
|o13 : H                                      |
+---------------------------------------------+
|i14 : h2 = homologyClass(KR,z2)              |
|                                             |
|o14 = X                                      |
|       3                                     |
|                                             |
|o14 : H                                      |
+---------------------------------------------+
|i15 : h3 = homologyClass(KR,z3)              |
|                                             |
|o15 = X                                      |
|       2                                     |
|                                             |
|o15 : H                                      |
+---------------------------------------------+
|i16 : h123 = masseyTripleProduct(KR,h1,h2,h3)|
|                                             |
|o16 = -X                                     |
|        31                                   |
|                                             |
|o16 : H                                      |
+---------------------------------------------+
|i17 : h123 == homologyClass(KR,z123)         |
|                                             |
|o17 = true                                   |
+---------------------------------------------+

Ways to use masseyTripleProduct:
================================

  * "masseyTripleProduct(DGAlgebra,RingElement,RingElement,RingElement)"
  * masseyTripleProduct(DGAlgebra,ZZ,ZZ,ZZ)
    -- Computes the matrix
    representing all triple Massey operations.

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8619:0.

masseyTripleProduct(DGAlgebra,ZZ,ZZ,ZZ) -- Computes the matrix representing all triple Massey operations.
*********************************************************************************************************

  * Function: masseyTripleProduct,
  * Usage:
        mat = masseyTripleProduct(A,l,m,n)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * l, an integer (Macaulay2Doc),
      * m, an integer (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
  * Outputs:
      * mat, a matrix (Macaulay2Doc),

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

Given a triple of homology classes h1,h2,h3, such that h1h2 = h2h3 = 0, the
Massey triple product of h1,h2 and h3 may be defined as in
masseyTripleProduct.  This command computes a basis of
the homology algebra of A in degrees l,m and n respectively, and expresses the
triple Massey operation of each triple, provided it is defined.  If a triple
product is not defined (i.e. if either h1h2 or h2h3 is not zero) then the
triple product is reported as zero in the matrix.

The following example appears in "On the Hopf algebra of a Local Ring" by
Avramov as an example of a nonvanishing Massey operation which an algebra
generator:

+-----------------------------------------------------------------------------+
|i1 : Q = QQ[t_1,t_2,t_3,t_4]                                                 |
|                                                                             |
|o1 = Q                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal (t_1^3,t_2^3,t_3^3-t_1*t_2^2,t_1^2*t_3^2,t_1*t_2*t_3^2,t_2^2*t|
|                                                                             |
|             3   3       2    3   2 2       2   2     2                      |
|o2 = ideal (t , t , - t t  + t , t t , t t t , t t , t )                     |
|             1   2     1 2    3   1 3   1 2 3   2 4   4                      |
|                                                                             |
|o2 : Ideal of Q                                                              |
|-----------------------------------------------------------------------------|
|_4,t_4^2)                                                                    |
+-----------------------------------------------------------------------------+
|i3 : R = Q/I                                                                 |
|                                                                             |
|o3 = R                                                                       |
|                                                                             |
|o3 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i4 : KR = koszulComplexDGA R                                                 |
|                                                                             |
|o4 = {Ring => R                          }                                   |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   1,4                                     |
|      Differential => {t , t , t , t }                                       |
|                        1   2   3   4                                        |
|                                                                             |
|o4 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i5 : H = HH(KR)                                                              |
|Finding easy relations           :  -- used 0.220013s (cpu); 0.216628s       |
|                                                                             |
|o5 = H                                                                       |
|                                                                             |
|o5 : QuotientRing                                                            |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i6 : masseys = masseyTripleProduct(KR,1,1,1);                                |
|                                                                             |
|              5       343                                                    |
|o6 : Matrix QQ  <-- QQ                                                       |
+-----------------------------------------------------------------------------+
|i7 : rank masseys                                                            |
|                                                                             |
|o7 = 1                                                                       |
+-----------------------------------------------------------------------------+

As you can see, this command is useful to determine the number of linearly
independent elements that arise as triple Massey products.

For example, the following Massey triple product is nonvanishing and is an
algebra generator:

+----------------------------------------+
|i8 : masseyTripleProduct(KR,X_2,X_4,X_1)|
|                                        |
|o8 = X                                  |
|      21                                |
|                                        |
|o8 : H                                  |
+----------------------------------------+

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

  * masseyTripleProduct(DGAlgebra,ZZ,ZZ,ZZ)
    -- Computes the matrix
    representing all triple Massey operations.
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8663:0.

maxDegree -- Computes the maximum homological degree of a DGAlgebra
*******************************************************************

  * Usage:
        mDegree = maxDegree(A)
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Outputs:
      * mDegree, an integer (Macaulay2Doc), The maximum degree of the
        DGAlgebra A (this can be infinite).

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

Note that if the DGAlgebra A has any generators of even degree, then maxDegree
returns infinity.

+-------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c,d]/ideal{a^3,b^3,c^3,d^3}                    |
|                                                                   |
|o1 = R                                                             |
|                                                                   |
|o1 : QuotientRing                                                  |
+-------------------------------------------------------------------+
|i2 : A = koszulComplexDGA(R)                                       |
|                                                                   |
|o2 = {Ring => R                          }                         |
|      Underlying algebra => R[T   ..T   ]                          |
|                               1,1   1,4                           |
|      Differential => {a, b, c, d}                                 |
|                                                                   |
|o2 : DGAlgebra                                                     |
+-------------------------------------------------------------------+
|i3 : B = acyclicClosure(A,EndDegree=>3)                            |
|                                                                   |
|o3 = {Ring => R                                                   }|
|      Underlying algebra => R[T   ..T   ]                          |
|                               1,1   2,4                           |
|                                    2       2       2       2      |
|      Differential => {a, b, c, d, a T   , b T   , c T   , d T   } |
|                                      1,1     1,2     1,3     1,4  |
|                                                                   |
|o3 : DGAlgebra                                                     |
+-------------------------------------------------------------------+
|i4 : maxDegree(A)                                                  |
|                                                                   |
|o4 = 4                                                             |
+-------------------------------------------------------------------+
|i5 : maxDegree(B)                                                  |
|                                                                   |
|o5 = infinity                                                      |
|                                                                   |
|o5 : InfiniteNumber                                                |
+-------------------------------------------------------------------+

Ways to use maxDegree:
======================

  * "maxDegree(DGAlgebra)"
  * maxDegree(DGModule) -- Largest hom-degree
    present in a DG module
  * maxDegree(DGQuotientModule), --
    Largest hom-degree present in a DG quotient module

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8242:0.

minimalModel -- Build the minimal DG algebra resolution of a quotient ring
**************************************************************************

  * Usage:
        A = minimalModel I
        A = minimalModel R
        A = minimalModel(I, EndDegree => n)
  * Inputs:
      * I, an ideal (Macaulay2Doc), An ideal in a polynomial ring
        Q.
      * R, a quotient ring (Macaulay2Doc), A quotient Q/I,
        where Q is a polynomial ring. The defining ideal ideal R (in ambient R
        = Q) is used.
  * Optional inputs (Macaulay2Doc),:
      * StartDegree => an integer (Macaulay2Doc), default value 1,
        First hom-degree at which to start killing homology.  Defaults to 1.
      * EndDegree => an integer (Macaulay2Doc), default value 3, Last
        hom-degree at which to kill homology.  Defaults to 3.
      * Variable => a string (Macaulay2Doc), default value null,
        Name of the divided-power generators; defaults to "T".
  * Outputs:
      * A, an instance of the type DGAlgebra, A DG algebra
        over Q whose degree-zero homology is Q/I and whose positive-degree
        homology is killed through hom-degree EndDegree.  In other words, a
        truncation of the minimal DG algebra resolution of Q/I as a Q-algebra.

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

Given an ideal I in a polynomial ring Q, minimalModel I is a shorthand for

acyclicClosure(koszulComplexDGA I) .

The Koszul DG algebra on a generating set of I has H_0 = Q/I, and
acyclicClosure adjoins divided-power variables in successively higher
hom-degrees to kill all positive homology, following Tate's construction.  The
result is a semifree DG algebra resolution of Q/I over Q in the sense of
Avramov, minimal in each hom-degree. When R = Q/I is passed, the defining ideal
of R inside its ambient polynomial ring is used.

For a complete intersection, the Koszul complex on a minimal generating set is
already acyclic in positive degrees, so minimalModel returns just that Koszul
DG algebra:

+---------------------------------------------+
|i1 : Q = ZZ/101[x, y]                        |
|                                             |
|o1 = Q                                       |
|                                             |
|o1 : PolynomialRing                          |
+---------------------------------------------+
|i2 : I = ideal(x^2, y^2)                     |
|                                             |
|             2   2                           |
|o2 = ideal (x , y )                          |
|                                             |
|o2 : Ideal of Q                              |
+---------------------------------------------+
|i3 : A = minimalModel(I, EndDegree => 3)     |
|                                             |
|o3 = {Ring => Q                          }   |
|      Underlying algebra => Q[T   ..T   ]    |
|                               1,1   1,2     |
|                        2   2                |
|      Differential => {x , y }               |
|                                             |
|o3 : DGAlgebra                               |
+---------------------------------------------+
|i4 : apply(0..3, n -> numcols getBasis(n, A))|
|                                             |
|o4 = (1, 2, 1, 0)                            |
|                                             |
|o4 : Sequence                                |
+---------------------------------------------+

The QuotientRing form is equivalent:

+--------------------------------------------+
|i5 : R = Q / I                              |
|                                            |
|o5 = R                                      |
|                                            |
|o5 : QuotientRing                           |
+--------------------------------------------+
|i6 : A' = minimalModel(R, EndDegree => 3)   |
|                                            |
|o6 = {Ring => Q                          }  |
|      Underlying algebra => Q[T   ..T   ]   |
|                               1,1   1,2    |
|                        2   2               |
|      Differential => {x , y }              |
|                                            |
|o6 : DGAlgebra                              |
+--------------------------------------------+
|i7 : numgens A.natural == numgens A'.natural|
|                                            |
|o7 = true                                   |
+--------------------------------------------+

For a non-complete-intersection ideal the acyclic closure genuinely adjoins
higher divided-power generators:

+-----------------------------------------------------------------------------+
|i8 : J = ideal(x^2, x*y, y^2)                                                |
|                                                                             |
|             2        2                                                      |
|o8 = ideal (x , x*y, y )                                                     |
|                                                                             |
|o8 : Ideal of Q                                                              |
+-----------------------------------------------------------------------------+
|i9 : B = minimalModel(J, EndDegree => 3)                                     |
|                                                                             |
|o9 = {Ring => Q                                                              |
|      Underlying algebra => Q[T   ..T   , T   ..T   , T   ..T   ,            |
|                               1,1   1,3   2,1   2,2   3,1   3,3             |
|                        2        2                                           |
|      Differential => {x , x*y, y , - y*T    + x*T   , - y*T    +            |
|                                         1,1      1,2       1,2              |
|                                                                             |
|o9 : DGAlgebra                                                               |
|-----------------------------------------------------------------------------|
|                                                                             |
|T   ..T   ]                                                                  |
| 4,1   4,6                                                                   |
|                                                                             |
|x*T   , - T   T    + x*T   , - T   T    + y*T   , - T   T    + y*T    +      |
|   1,3     1,1 1,2      2,1     1,2 1,3      2,2     1,1 1,3      2,1        |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|x*T   , - T   T    + y*T   , - T   T    + x*T   , - T   T    + y*T   , -     |
|   2,2     1,2 2,1      3,1     1,1 2,1      3,1     1,3 2,2      3,2        |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|T   T    + x*T   , - T   T    - T   T    + y*T   , - T   T    - T   T    +   |
| 1,2 2,2      3,2     1,3 2,1    1,2 2,2      3,3     1,2 2,1    1,1 2,2     |
|-----------------------------------------------------------------------------|
|       }                                                                     |
|                                                                             |
|                                                                             |
|                                                                             |
|x*T   }                                                                      |
|   3,3                                                                       |
+-----------------------------------------------------------------------------+
|i10 : apply(0..3, n -> numcols getBasis(n, B))                               |
|                                                                             |
|o10 = (1, 3, 5, 10)                                                          |
|                                                                             |
|o10 : Sequence                                                               |
+-----------------------------------------------------------------------------+

As with acyclicClosure, EndDegree truncates the
construction and Variable renames the adjoined generators:

+----------------------------------------------------------+
|i11 : C = minimalModel(I, EndDegree => 2, Variable => "S")|
|                                                          |
|o11 = {Ring => Q                          }               |
|       Underlying algebra => Q[S   ..S   ]                |
|                                1,1   1,2                 |
|                         2   2                            |
|       Differential => {x , y }                           |
|                                                          |
|o11 : DGAlgebra                                           |
+----------------------------------------------------------+
|i12 : gens C.natural                                      |
|                                                          |
|o12 = {S   , S   }                                        |
|        1,1   1,2                                         |
|                                                          |
|o12 : List                                                |
+----------------------------------------------------------+

Deviations and Gulliksen's theorem.  The rank of A in hom-degree n is the n-th
deviation of Q/I, a classical invariant which vanishes for n >= 2 if and only
if Q/I is a complete intersection (Gulliksen-Avramov).  Compare the two shapes:

+--------------------------------------------------------------+
|i13 : A1 = minimalModel(ideal(x^2, y^2), EndDegree => 4);     |
+--------------------------------------------------------------+
|i14 : apply(0..4, n -> numcols getBasis(n, A1))               |
|                                                              |
|o14 = (1, 2, 1, 0, 0)                                         |
|                                                              |
|o14 : Sequence                                                |
+--------------------------------------------------------------+
|i15 : A2 = minimalModel(ideal(x^2, x*y, y^2), EndDegree => 4);|
+--------------------------------------------------------------+
|i16 : apply(0..4, n -> numcols getBasis(n, A2))               |
|                                                              |
|o16 = (1, 3, 5, 10, 24)                                       |
|                                                              |
|o16 : Sequence                                                |
+--------------------------------------------------------------+

A1 concentrates in hom-degrees 0, 1 (the hallmark of a c.i.), while A2 keeps
acquiring divided-power generators, showing that Q/(x^2, xy, y^2) is not a c.i.
Running minimalSemifreeResolution, on the
residue field over the minimal model then gives a test of Gulliksen's theorem,
which states that over a codimension-c complete intersection the Betti numbers
of any finitely generated module are eventually polynomial in the hom-degree,
of degree at most c - 1:

+--------------------------------------------------------------+
|i17 : A = minimalModel(ideal(x^2, y^2), EndDegree => 8);      |
+--------------------------------------------------------------+
|i18 : k = Q^1 / ideal(x, y);                                  |
+--------------------------------------------------------------+
|i19 : Mdg = minimalSemifreeResolution(A, k, EndDegree => 8);  |
+--------------------------------------------------------------+
|i20 : b = apply(0..8, n -> numcols moduleDifferential(n, Mdg))|
|                                                              |
|o20 = (1, 4, 8, 12, 16, 20, 24, 28, 32)                       |
|                                                              |
|o20 : Sequence                                                |
+--------------------------------------------------------------+
|i21 : apply(0..7, n -> b#(n+1) - b#n)                         |
|                                                              |
|o21 = (3, 4, 4, 4, 4, 4, 4, 4)                                |
|                                                              |
|o21 : Sequence                                                |
+--------------------------------------------------------------+
|i22 : apply(0..6, n -> b#(n+2) - 2*b#(n+1) + b#n)             |
|                                                              |
|o22 = (1, 0, 0, 0, 0, 0, 0)                                   |
|                                                              |
|o22 : Sequence                                                |
+--------------------------------------------------------------+

The Betti sequence is (1, 4, 8, 12, 16, 20, 24, 28, 32); first differences
stabilize to a constant and second differences are eventually 0, so the numbers
are eventually linear -- a degree-1 polynomial, matching codimension 2.  A
codimension-3 c.i. such as (x^2, y^2, z^2) would instead show second
differences stabilizing nonzero and third differences vanishing.

Caveat
======

The ring of A is always the polynomial ring containing the relations -- that
is, ring I or ambient R, not the quotient itself.  This matches the standard
convention that the minimal DG algebra resolution of Q/I lives over Q.

See also
========

  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension
  * acyclicClosure(Ring) -- Tate's acyclic
    closure of the residue field, starting from the Koszul complex
  * koszulComplexDGA -- The Koszul complex on the
    variables of a ring, as a DG algebra
  * koszulComplexDGA(Ideal) -- The Koszul
    complex on the generators of an ideal, as a DG algebra

Ways to use minimalModel:
=========================

  * "minimalModel(Ideal)"
  * "minimalModel(QuotientRing)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1653:0.

minimizeDGModule
****************

Ways to use minimizeDGModule:
=============================

  * minimizeDGModule(DGModule) (missing documentation)

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

The object minimizeDGModule (missing documentation) is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in currentString:1:376.

natural -- The underlying graded-commutative ring of a DGAlgebra or DGModule
****************************************************************************

  * Usage:
        Anat = A.natural

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

For a DGAlgebra, A, the key A.natural holds the underlying
graded-commutative polynomial ring of A with the differential forgotten.  This
is the ambient ring in which algebra generators live, in which cycles and
boundaries are expressed, and against which differentials are compared.  It is
always a polynomial ring over A.ring (with the skew-commutative flag set on
odd-hom-degree generators), never a quotient.

+---------------------------------------------------+
|i1 : R = ZZ/101[a, b, c, d]                        |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : A = koszulComplexDGA R                        |
|                                                   |
|o2 = {Ring => R                          }         |
|      Underlying algebra => R[T   ..T   ]          |
|                               1,1   1,4           |
|      Differential => {a, b, c, d}                 |
|                                                   |
|o2 : DGAlgebra                                     |
+---------------------------------------------------+
|i3 : A.natural                                     |
|                                                   |
|o3 = R[T   ..T   ]                                 |
|        1,1   1,4                                  |
|                                                   |
|o3 : PolynomialRing, 4 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : A.ring === R                                  |
|                                                   |
|o4 = true                                          |
+---------------------------------------------------+
|i5 : gens A.natural                                |
|                                                   |
|o5 = {T   , T   , T   , T   }                      |
|       1,1   1,2   1,3   1,4                       |
|                                                   |
|o5 : List                                          |
+---------------------------------------------------+

For a DGModule, M, the same key holds the underlying free
A.natural-module with the differential forgotten.  The differential is recorded
separately in M.diff and the multi-degrees of the natural generators in
M.Degrees:

+-----------------------------------------------------------------+
|i6 : B = freeDGModule(A, {0, 1, 2})                              |
|                                                                 |
|o6 = {Base ring => R                               }             |
|      DG algebra => R[T   ..T   ]                                |
|                       1,1   1,4                                 |
|                                       3                         |
|      Natural module => (R[T   ..T   ])                          |
|                            1,1   1,4                            |
|      Generator degrees => {{0, 0}, {1, 0}, {2, 0}}              |
|      Differentials on gens => {0, 0, 0}                         |
|                                                                 |
|o6 : DGModule                                                    |
+-----------------------------------------------------------------+
|i7 : B.natural                                                   |
|                                                                 |
|                    3                                            |
|o7 = (R[T   ..T   ])                                             |
|         1,1   1,4                                               |
|                                                                 |
|o7 : R[T   ..T   ]-module, free, degrees {{0, 0}, {1, 0}, {2, 0}}|
|        1,1   1,4                                                |
+-----------------------------------------------------------------+
|i8 : rank B.natural                                              |
|                                                                 |
|o8 = 3                                                           |
+-----------------------------------------------------------------+

See also
========

  * DGAlgebra -- The class of all DGAlgebras
  * DGModule -- The class of DG modules over a DG algebra
  * ring (Macaulay2Doc) -- get the associated ring of an object

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

The object natural, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1198:0.

net(DGAlgebra) -- Short-form display of a DG algebra
****************************************************

  * Function: net (Macaulay2Doc),
  * Usage:
        net A
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Outputs:
      * a net (Macaulay2Doc), a one-line summary of A

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

Produces the text Macaulay2 prints when a DGAlgebra, appears
at the top level.  The display names the underlying ring, the generators of
A.natural, and any differentials known so far, giving a compact identifier
rather than a full data dump.  Use peek A or displayBlockDiff for a detailed
view of the internal state.

+---------------------------------------------+
|i1 : R = ZZ/101[x,y,z] / ideal(x^3, y^3, z^3)|
|                                             |
|o1 = R                                       |
|                                             |
|o1 : QuotientRing                            |
+---------------------------------------------+
|i2 : A = koszulComplexDGA R                  |
|                                             |
|o2 = {Ring => R                          }   |
|      Underlying algebra => R[T   ..T   ]    |
|                               1,1   1,3     |
|      Differential => {x, y, z}              |
|                                             |
|o2 : DGAlgebra                               |
+---------------------------------------------+
|i3 : net A                                   |
|                                             |
|o3 = {Ring => R                          }   |
|      Underlying algebra => R[T   ..T   ]    |
|                               1,1   1,3     |
|      Differential => {x, y, z}              |
+---------------------------------------------+
|i4 : A                                       |
|                                             |
|o4 = {Ring => R                          }   |
|      Underlying algebra => R[T   ..T   ]    |
|                               1,1   1,3     |
|      Differential => {x, y, z}              |
|                                             |
|o4 : DGAlgebra                               |
+---------------------------------------------+

See also
========

  * DGAlgebra -- The class of all DGAlgebras
  * displayBlockDiff -- Shows natural decomposition of
    a map in the Tate resolution

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

  * net(DGAlgebra) -- Short-form display of a DG
    algebra
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9850:0.

net(DGAlgebraMap) -- Short-form display of a DG algebra map
***********************************************************

  * Function: net (Macaulay2Doc),
  * Usage:
        net phi
  * Inputs:
      * phi, an instance of the type DGAlgebraMap,
  * Outputs:
      * a net (Macaulay2Doc), a short summary of phi

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

Produces the text Macaulay2 prints when a DGAlgebraMap, is
displayed at the top level.  The output lists the action of phi on the
generators of the underlying algebra, using the information stored in
phi.natural.

+--------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c]/ideal{a^3 + b^3 + c^3, a*b*c}          |
|                                                              |
|o1 = R                                                        |
|                                                              |
|o1 : QuotientRing                                             |
+--------------------------------------------------------------+
|i2 : K1 = koszulComplexDGA(ideal vars R, Variable => "Y")     |
|                                                              |
|o2 = {Ring => R                          }                    |
|      Underlying algebra => R[Y   ..Y   ]                     |
|                               1,1   1,3                      |
|      Differential => {a, b, c}                               |
|                                                              |
|o2 : DGAlgebra                                                |
+--------------------------------------------------------------+
|i3 : K2 = koszulComplexDGA(ideal{b, c}, Variable => "T")      |
|                                                              |
|o3 = {Ring => R                          }                    |
|      Underlying algebra => R[T   ..T   ]                     |
|                               1,1   1,2                      |
|      Differential => {b, c}                                  |
|                                                              |
|o3 : DGAlgebra                                                |
+--------------------------------------------------------------+
|i4 : g = dgAlgebraMap(K1, K2, matrix{{Y_(1,2), Y_(1,3)}})     |
|                                                              |
|o4 = map (R[Y   ..Y   ], R[T   ..T   ], {Y   , Y   , a, b, c})|
|             1,1   1,3      1,1   1,2     1,2   1,3           |
|                                                              |
|o4 : DGAlgebraMap                                             |
+--------------------------------------------------------------+
|i5 : net g                                                    |
|                                                              |
|o5 = map (R[Y   ..Y   ], R[T   ..T   ], {Y   , Y   , a, b, c})|
|             1,1   1,3      1,1   1,2     1,2   1,3           |
+--------------------------------------------------------------+
|i6 : g                                                        |
|                                                              |
|o6 = map (R[Y   ..Y   ], R[T   ..T   ], {Y   , Y   , a, b, c})|
|             1,1   1,3      1,1   1,2     1,2   1,3           |
|                                                              |
|o6 : DGAlgebraMap                                             |
+--------------------------------------------------------------+

See also
========

  * DGAlgebraMap -- The class of DG algebra maps
  * dgAlgebraMap -- Define a DG algebra map between DG
    algebras.

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

  * net(DGAlgebraMap) -- Short-form display of a
    DG algebra map
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9879:0.

RelDegreeLimit -- Option to bound the homological degree searched for algebra relations
***************************************************************************************

  * Usage:
        homologyAlgebra(..., RelDegreeLimit => n)
        torAlgebra(..., RelDegreeLimit => n)

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

Once generators have been chosen (see GenDegreeLimit), a
homology algebra computation must determine relations among them.
RelDegreeLimit bounds the homological degree up to which those relations are
searched.  Typical practice is to set RelDegreeLimit to roughly twice
GenDegreeLimit, since relations can be degree-sums of generator pairs.

See also
========

  * GenDegreeLimit -- Option to bound the homological
    degree searched for algebra generators
  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.
  * torAlgebra -- Computes the Tor algebra of a ring

Functions with optional argument named RelDegreeLimit:
======================================================

  * homologyAlgebra(...,RelDegreeLimit=>...)
    -- Maximum
    homological degree searched for homology-algebra relations
  * torAlgebra(...,RelDegreeLimit=>...)
    -- Maximum
    homological degree searched for Tor-algebra relations

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

The object RelDegreeLimit, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9404:0.

ringMap -- The degree-zero ring map underlying a DGAlgebraMap
*************************************************************

  * Usage:
        phi.ringMap

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

Every DGAlgebraMap, phi from A to B includes a key ringMap:
a RingMap (Macaulay2Doc), from A.ring to B.ring giving the
restriction of phi to degree zero.  When the two DG algebras live over the same
ring, phi.ringMap is the identity; in general it is the degree-zero ring map
used to lift phi.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c]/ideal{a^3, b^3, c^3}                                  |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : S = R / ideal{a^2*b^2*c^2}                                              |
|                                                                             |
|o2 = S                                                                       |
|                                                                             |
|o2 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i3 : A = acyclicClosure(R, EndDegree => 2)                                   |
|                                                                             |
|o3 = {Ring => R                                        }                     |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   2,3                                     |
|                                 2       2       2                           |
|      Differential => {a, b, c, a T   , b T   , c T   }                      |
|                                   1,1     1,2     1,3                       |
|                                                                             |
|o3 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i4 : B = acyclicClosure(S, EndDegree => 2)                                   |
|                                                                             |
|o4 = {Ring => S                                                              |
|      Underlying algebra => S[T   ..T   , T   ..T   , T   ..T   ]            |
|                               1,1   1,3   2,1   2,4   3,1   3,3             |
|                                 2       2       2         2 2       2 2     |
|      Differential => {a, b, c, a T   , b T   , c T   , a*b c T   , b c T   ,|
|                                   1,1     1,2     1,3         1,1       2,1 |
|                                                                             |
|o4 : DGAlgebra                                                               |
|-----------------------------------------------------------------------------|
|                     }                                                       |
|                                                                             |
|                                                                             |
|  2 2        2 2                                                             |
|-a b T   , -a c T   }                                                        |
|      2,3        2,2                                                         |
+-----------------------------------------------------------------------------+
|i5 : phi = liftToDGMap(B, A, map(S, R))                                      |
|                                                                             |
|o5 = map (S[T   ..T   , T   ..T   , T   ..T   ], R[T   ..T   ], {T   , T   , |
|             1,1   1,3   2,1   2,4   3,1   3,3      1,1   2,3     1,1   1,2  |
|                                                                             |
|o5 : DGAlgebraMap                                                            |
|-----------------------------------------------------------------------------|
|T   , T   , T   , T   , a, b, c})                                            |
| 1,3   2,1   2,2   2,3                                                       |
+-----------------------------------------------------------------------------+
|i6 : phi.ringMap                                                             |
|                                                                             |
|o6 = map (S, R, {a, b, c})                                                   |
|                                                                             |
|o6 : RingMap S <-- R                                                         |
+-----------------------------------------------------------------------------+

The ringMap is the bridge used internally by toComplexMap,
to pushforward complexes between different rings.

See also
========

  * DGAlgebraMap -- The class of DG algebra maps
  * liftToDGMap -- Lift a ring homomorphism in degree zero
    to a DG algebra morphism
  * toComplexMap -- Construct the ComplexMap associated to
    a DGAlgebraMap

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

The object ringMap, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8989:0.

setDiff -- Install or replace the differential on a DG algebra
**************************************************************

  * Usage:
        A = setDiff(A, diffList)
        A = setDiff(A, diffList, InitializeComplex => false)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * diffList, a list (Macaulay2Doc), A list of elements of
        A.natural, one per algebra generator, given in the same order as gens
        A.natural (which is the order of A.Degrees).  The i-th entry becomes
        d((gens A.natural)_i) and is extended to all of A.natural by
        R-linearity and the Leibniz rule. Each entry must have homological
        degree one less than its generator.
  * Optional inputs (Macaulay2Doc),:
      * InitializeComplex => a Boolean value (Macaulay2Doc),
        default value true, Whether to eagerly compute all differential
        matrices up to maxDegree A.  Defaults to true; set to false to skip the
        precomputation when only a low-degree fragment is needed.
      * InitializeDegreeZeroHomology => a Boolean value (Macaulay2Doc),
        default value true, Whether to compute the
        quotient ring H_0(A) (needed by homologyAlgebra).
        Defaults to true; set to false to skip the
        Grobner-basis computation when not needed.
  * Outputs:
      * A, an instance of the type DGAlgebra, The same A, now
        with its diff field populated; returned for convenience in a chained
        call.

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

Because the ring A.natural does not exist until after freeDGAlgebra,
runs, the differential cannot be passed to the constructor and
must be set afterwards with setDiff. The list diffList supplies the image of
each algebra generator; Leibniz and R-linearity extend this to every element of
A.natural.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[x, y, z]                                                     |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : A = freeDGAlgebra(R, {{1}, {1}, {1}, {3}})                              |
|                                                                             |
|o2 = {Ring => R                                }                             |
|      Underlying algebra => R[T   ..T   , T   ]                              |
|                               1,1   1,3   3,1                               |
|      Differential => null                                                   |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : gens A.natural                                                          |
|                                                                             |
|o3 = {T   , T   , T   , T   }                                                |
|       1,1   1,2   1,3   3,1                                                 |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : setDiff(A, {x, y, z, x*T_(1,2)*T_(1,3) - y*T_(1,1)*T_(1,3) + z*T_(1,1)*T|
|                                                                             |
|o4 = {Ring => R                                                      }       |
|      Underlying algebra => R[T   ..T   , T   ]                              |
|                               1,1   1,3   3,1                               |
|      Differential => {x, y, z, z*T   T    - y*T   T    + x*T   T   }        |
|                                   1,1 1,2      1,1 1,3      1,2 1,3         |
|                                                                             |
|o4 : DGAlgebra                                                               |
|-----------------------------------------------------------------------------|
|_(1,2)})                                                                     |
+-----------------------------------------------------------------------------+
|i5 : flatten entries matrix A.diff                                           |
|                                                                             |
|o5 = {x, y, z, z*T   T    - y*T   T    + x*T   T   , x, y, z}                |
|                  1,1 1,2      1,1 1,3      1,2 1,3                          |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

Here d(T_(1,i)) = x_i (so the Koszul piece on T_(1,*) is installed) and
d(T_(3,1)) is the Koszul-relation 2-cycle x T_(1,2) T_(1,3) - y T_(1,1) T_(1,3)
+ z T_(1,1) T_(1,2), turning A into a Tate-resolution fragment for R/(x, y, z).
Converting to a Complex (Complexes), shows the installed
differentials:

+-------------------------------------------------+
|i6 : Acomplex = toComplex A                      |
|                                                 |
|      1      3      3      2      3      3      1|
|o6 = R  <-- R  <-- R  <-- R  <-- R  <-- R  <-- R |
|                                                 |
|     0      1      2      3      4      5      6 |
|                                                 |
|o6 : Complex                                     |
+-------------------------------------------------+
|i7 : Acomplex.dd_1                               |
|                                                 |
|o7 = | x y z |                                   |
|                                                 |
|             1      3                            |
|o7 : Matrix R  <-- R                             |
+-------------------------------------------------+
|i8 : Acomplex.dd_2                               |
|                                                 |
|o8 = | -y -z 0  |                                |
|     | x  0  -z |                                |
|     | 0  x  y  |                                |
|                                                 |
|             3      3                            |
|o8 : Matrix R  <-- R                             |
+-------------------------------------------------+

Validity.  The package does not check that the installed differential squares
to zero; a user-supplied diffList that violates d^2 = 0 yields a malformed DG
algebra with silently wrong downstream behavior.  The chain-map conditions can
be checked after the fact via isWellDefined(DGAlgebra).

Options.  InitializeComplex controls whether setDiff eagerly builds all
differential matrices up to maxDegree A (the sum of the hom-degrees of the
odd-hom-degree generators).  Set it to false to defer this computation when
only low-degree information is needed:

+-----------------------------------------------------------------------------+
|i9 : Abig = freeDGAlgebra(R, {{1}, {1}, {1}, {3}})                           |
|                                                                             |
|o9 = {Ring => R                                }                             |
|      Underlying algebra => R[T   ..T   , T   ]                              |
|                               1,1   1,3   3,1                               |
|      Differential => null                                                   |
|                                                                             |
|o9 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i10 : setDiff(Abig, {x, y, z, x*T_(1,2)*T_(1,3) - y*T_(1,1)*T_(1,3) + z*T_(1,|
|                                                                             |
|o10 = {Ring => R                                                      }      |
|       Underlying algebra => R[T   ..T   , T   ]                             |
|                                1,1   1,3   3,1                              |
|       Differential => {x, y, z, z*T   T    - y*T   T    + x*T   T   }       |
|                                    1,1 1,2      1,1 1,3      1,2 1,3        |
|                                                                             |
|o10 : DGAlgebra                                                              |
|-----------------------------------------------------------------------------|
|1)*T_(1,2)}, InitializeComplex => false)                                     |
+-----------------------------------------------------------------------------+

InitializeDegreeZeroHomology controls whether the quotient ring H_0(A) = A_0 /
image(d_1) is computed on the spot (a Grobner-basis computation, deferred to
homologyAlgebra, if turned off).  Default: true.  Turn
it off if you have many hom-degree-1 generators and are not about to compute HH
A as a DG algebra.

Caveat
======

The order of entries in diffList must match the order of generators in gens
A.natural (equivalently, of A.Degrees).  For constructors that adjoin
generators incrementally (see adjoinVariables,
acyclicClosure, killCycles), the new
generators come after all existing ones in this ordering.

See also
========

  * freeDGAlgebra -- Construct a free DG algebra with
    given generator degrees
  * koszulComplexDGA -- The Koszul complex on the
    variables of a ring, as a DG algebra
  * adjoinVariables -- Extend a DG algebra by a
    user-chosen list of cycles to be killed
  * isWellDefined(DGAlgebra) -- Check that
    a DG algebra has correct structure and a differential that squares to zero
  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.

Ways to use setDiff:
====================

  * "setDiff(DGAlgebra,List)"
  * setDiff(DGModule,List) -- Install the
    list of generator differentials on a free DG module

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1137:0.

source(DGAlgebraMap) -- The source of a DG algebra map
******************************************************

  * Function: source (Macaulay2Doc),
  * Usage:
        A = source phi
  * Inputs:
      * phi, an instance of the type DGAlgebraMap,
  * Outputs:
      * A, an instance of the type DGAlgebra, the source DG
        algebra of phi

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

Returns the DGAlgebra, from which phi is defined.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c]/ideal{a^3, b^3, c^3}                                  |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : S = R / ideal{a^2*b^2*c^2}                                              |
|                                                                             |
|o2 = S                                                                       |
|                                                                             |
|o2 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i3 : A = acyclicClosure(R, EndDegree => 2)                                   |
|                                                                             |
|o3 = {Ring => R                                        }                     |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   2,3                                     |
|                                 2       2       2                           |
|      Differential => {a, b, c, a T   , b T   , c T   }                      |
|                                   1,1     1,2     1,3                       |
|                                                                             |
|o3 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i4 : B = acyclicClosure(S, EndDegree => 2)                                   |
|                                                                             |
|o4 = {Ring => S                                                              |
|      Underlying algebra => S[T   ..T   , T   ..T   , T   ..T   ]            |
|                               1,1   1,3   2,1   2,4   3,1   3,3             |
|                                 2       2       2         2 2       2 2     |
|      Differential => {a, b, c, a T   , b T   , c T   , a*b c T   , b c T   ,|
|                                   1,1     1,2     1,3         1,1       2,1 |
|                                                                             |
|o4 : DGAlgebra                                                               |
|-----------------------------------------------------------------------------|
|                     }                                                       |
|                                                                             |
|                                                                             |
|  2 2        2 2                                                             |
|-a b T   , -a c T   }                                                        |
|      2,3        2,2                                                         |
+-----------------------------------------------------------------------------+
|i5 : phi = liftToDGMap(B, A, map(S, R))                                      |
|                                                                             |
|o5 = map (S[T   ..T   , T   ..T   , T   ..T   ], R[T   ..T   ], {T   , T   , |
|             1,1   1,3   2,1   2,4   3,1   3,3      1,1   2,3     1,1   1,2  |
|                                                                             |
|o5 : DGAlgebraMap                                                            |
|-----------------------------------------------------------------------------|
|T   , T   , T   , T   , a, b, c})                                            |
| 1,3   2,1   2,2   2,3                                                       |
+-----------------------------------------------------------------------------+
|i6 : source phi === A                                                        |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * DGAlgebraMap -- The class of DG algebra maps
  * target(DGAlgebraMap) -- The target of a DG
    algebra map
  * liftToDGMap -- Lift a ring homomorphism in degree zero
    to a DG algebra morphism

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

  * source(DGAlgebraMap) -- The source of a DG
    algebra map
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9255:0.

StartDegree -- Option to specify the first homological degree processed by an iterative DG construction
*******************************************************************************************************

  * Usage:
        acyclicClosure(..., StartDegree => n)
        killCycles(..., StartDegree => n)
        getGenerators(..., StartDegree => n)

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

Several routines in this package build DG algebras one homological degree at a
time, starting from degree StartDegree and incrementing up to an appropriate
endpoint.  Raising StartDegree can be useful when a partial acyclic closure has
already been cached and you wish to continue the construction from where it
left off.  The default value is 1.

See also
========

  * EndDegree -- Option to specify the last homological
    degree processed by an iterative DG construction
  * acyclicClosure -- Tate's construction of a semifree
    acyclic DG algebra extension
  * killCycles -- Adjoin variables to kill non-bounding
    cycles in the lowest positive degree
  * getGenerators -- Cycles whose classes generate the
    homology algebra of a DG algebra

Functions with optional argument named StartDegree:
===================================================

  * acyclicClosure(...,StartDegree=>...)
    -- Option to
    specify the degree to start computing the acyclic closure.
  * getGenerators(...,StartDegree=>...)
    -- First homological
    degree in which to search for new algebra generators
  * killCycles(...,StartDegree=>...)
    -- First homological
    degree from which killCycles begins searching for cycles
  * "minimalModel(...,StartDegree=>...)" -- see minimalModel,
    -- Build the minimal DG algebra resolution of a quotient ring
  * minimalSemifreeResolution(...,StartDegree=>...),
    --
    Option to specify the degree at which minimalSemifreeResolution starts
    killing cycles
  * semifreeResolution(...,StartDegree=>...)
    -- Option to
    specify the degree at which semifreeResolution starts killing cycles

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

The object StartDegree, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9327:0.

target(DGAlgebraMap) -- The target of a DG algebra map
******************************************************

  * Function: target (Macaulay2Doc),
  * Usage:
        B = target phi
  * Inputs:
      * phi, an instance of the type DGAlgebraMap,
  * Outputs:
      * B, an instance of the type DGAlgebra, the target DG
        algebra of phi

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

Returns the DGAlgebra, into which phi maps.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c]/ideal{a^3, b^3, c^3}                                  |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : S = R / ideal{a^2*b^2*c^2}                                              |
|                                                                             |
|o2 = S                                                                       |
|                                                                             |
|o2 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i3 : A = acyclicClosure(R, EndDegree => 2)                                   |
|                                                                             |
|o3 = {Ring => R                                        }                     |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   2,3                                     |
|                                 2       2       2                           |
|      Differential => {a, b, c, a T   , b T   , c T   }                      |
|                                   1,1     1,2     1,3                       |
|                                                                             |
|o3 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i4 : B = acyclicClosure(S, EndDegree => 2)                                   |
|                                                                             |
|o4 = {Ring => S                                                              |
|      Underlying algebra => S[T   ..T   , T   ..T   , T   ..T   ]            |
|                               1,1   1,3   2,1   2,4   3,1   3,3             |
|                                 2       2       2         2 2       2 2     |
|      Differential => {a, b, c, a T   , b T   , c T   , a*b c T   , b c T   ,|
|                                   1,1     1,2     1,3         1,1       2,1 |
|                                                                             |
|o4 : DGAlgebra                                                               |
|-----------------------------------------------------------------------------|
|                     }                                                       |
|                                                                             |
|                                                                             |
|  2 2        2 2                                                             |
|-a b T   , -a c T   }                                                        |
|      2,3        2,2                                                         |
+-----------------------------------------------------------------------------+
|i5 : phi = liftToDGMap(B, A, map(S, R))                                      |
|                                                                             |
|o5 = map (S[T   ..T   , T   ..T   , T   ..T   ], R[T   ..T   ], {T   , T   , |
|             1,1   1,3   2,1   2,4   3,1   3,3      1,1   2,3     1,1   1,2  |
|                                                                             |
|o5 : DGAlgebraMap                                                            |
|-----------------------------------------------------------------------------|
|T   , T   , T   , T   , a, b, c})                                            |
| 1,3   2,1   2,2   2,3                                                       |
+-----------------------------------------------------------------------------+
|i6 : target phi === B                                                        |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * DGAlgebraMap -- The class of DG algebra maps
  * source(DGAlgebraMap) -- The source of a DG
    algebra map
  * liftToDGMap -- Lift a ring homomorphism in degree zero
    to a DG algebra morphism

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

  * target(DGAlgebraMap) -- The target of a DG
    algebra map
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9283:0.

TMOLimit -- Option to bound the arity of Massey operations searched for by findTrivialMasseyOperation
*****************************************************************************************************

  * Usage:
        findTrivialMasseyOperation(..., TMOLimit => n)
        isGolodHomomorphism(..., TMOLimit => n)

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

A trivial Massey operation on a DG algebra is a system of null-homotopies that
simultaneously trivialize every Massey product.  TMOLimit caps the arity of
Massey products considered: only k-fold products with k <= n are tested for
bounding.  This makes the search finite even when the full system would be
infinite.  In practice, TMOLimit values of 3 or 4 suffice for small examples.

See also
========

  * findTrivialMasseyOperation -- Finds a
    trivial Massey operation on a set of generators of H(A)
  * isGolodHomomorphism -- Determines if the
    canonical map from the ambient ring is Golod
  * isGolod -- Determines if a ring is Golod

Functions with optional argument named TMOLimit:
================================================

  * findTrivialMasseyOperation(...,TMOLimit=>...)
    -- Maximum
    arity of Massey products searched for bounding
  * isGolodHomomorphism(...,TMOLimit=>...)
    -- Option to cap
    the arity of the trivial Massey operation used in isGolodHomomorphism

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

The object TMOLimit, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9426:0.

toComplex -- Converts a DGAlgebra to a Complex
**********************************************

  * Usage:
        C = toComplex A or C = toComplex(A,n)
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Outputs:
      * C, a complex (Complexes), The DG algebra A as a Complex

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

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[x_1..x_10]                                                   |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : A = koszulComplexDGA(R)                                                 |
|                                                                             |
|o2 = {Ring => R                                                }             |
|      Underlying algebra => R[T   ..T    ]                                   |
|                               1,1   1,10                                    |
|      Differential => {x , x , x , x , x , x , x , x , x , x  }              |
|                        1   2   3   4   5   6   7   8   9   10               |
|                                                                             |
|o2 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i3 : C = toComplex A                                                         |
|                                                                             |
|      1      10      45      120      210      252      210      120      45 |
|o3 = R  <-- R   <-- R   <-- R    <-- R    <-- R    <-- R    <-- R    <-- R   |
|                                                                             |
|     0      1       2       3        4        5        6        7        8   |
|                                                                             |
|o3 : Complex                                                                 |
|-----------------------------------------------------------------------------|
|     10      1                                                               |
|<-- R   <-- R                                                                |
|                                                                             |
|    9       10                                                               |
+-----------------------------------------------------------------------------+

Warning:  The term order that the internal command koszul uses to order the
monomials is not GRevLex, and so the differentials used in koszul and
koszulComplexDGA will not match up exactly.  Also, this command will only
execute if all of the variables of the DGAlgebra, A are of odd
homological degree.  Otherwise, you need to use the function
toComplex(DGAlgebra,ZZ).

Ways to use toComplex:
======================

  * "toComplex(DGAlgebra)"
  * toComplex(DGAlgebra,ZZ) -- Converts a
    DGAlgebra to a Complex
  * toComplex(DGIdeal) -- Export a DG ideal to a
    Complex (not yet implemented)
  * toComplex(DGModule) -- Export a DG module
    to a Complex of free base-ring modules
  * toComplex(DGModule,ZZ) -- Export a DG
    module to a Complex with an explicit hom-degree bound
  * toComplex(DGQuotientModule), --
    Export a DG quotient module to a Complex

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1303:0.

toComplex(DGAlgebra,ZZ) -- Converts a DGAlgebra to a Complex
************************************************************

  * Function: toComplex,
  * Usage:
        C = toComplex A or C = toComplex(A,n)
  * Inputs:
      * A, an instance of the type DGAlgebra,
      * n, an integer (Macaulay2Doc),
  * Outputs:
      * C, a complex (Complexes), The DG algebra A as a Complex

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

+-------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c,d]/ideal{a^3,b^3,c^3,d^3}                    |
|                                                                   |
|o1 = R                                                             |
|                                                                   |
|o1 : QuotientRing                                                  |
+-------------------------------------------------------------------+
|i2 : A = acyclicClosure(R,EndDegree=>3)                            |
|                                                                   |
|o2 = {Ring => R                                                   }|
|      Underlying algebra => R[T   ..T   ]                          |
|                               1,1   2,4                           |
|                                    2       2       2       2      |
|      Differential => {a, b, c, d, a T   , b T   , c T   , d T   } |
|                                      1,1     1,2     1,3     1,4  |
|                                                                   |
|o2 : DGAlgebra                                                     |
+-------------------------------------------------------------------+

The above will be a resolution of the residue field over R, since R is a
complete intersection.

+-----------------------------------------------------------------------------+
|i3 : C = toComplex(A, 10)                                                    |
|                                                                             |
|      1      4      10      20      35      56      84      120      165     |
|o3 = R  <-- R  <-- R   <-- R   <-- R   <-- R   <-- R   <-- R    <-- R    <-- |
|                                                                             |
|     0      1      2       3       4       5       6       7        8        |
|                                                                             |
|o3 : Complex                                                                 |
|-----------------------------------------------------------------------------|
| 220      286                                                                |
|R    <-- R                                                                   |
|                                                                             |
|9        10                                                                  |
+-----------------------------------------------------------------------------+
|i4 : apply(10, i -> prune HH_i(C))                                           |
|                                                                             |
|o4 = {cokernel | d c b a |, 0, 0, 0, 0, 0, 0, 0, 0, 0}                       |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

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

  * toComplex(DGAlgebra,ZZ) -- Converts a
    DGAlgebra to a Complex
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:1327:0.

toComplexMap -- Construct the ComplexMap associated to a DGAlgebraMap
*********************************************************************

  * Usage:
        psi = toComplexMap phi
  * Inputs:
      * phi, an instance of the type DGAlgebraMap,
  * Optional inputs (Macaulay2Doc),:
      * AssertWellDefined => ..., default value true
      * EndDegree => ..., default value -1
  * Outputs:
      * psi, a map of complexes (Complexes),

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

+--------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c]/ideal{a^3+b^3+c^3,a*b*c}               |
|                                                              |
|o1 = R                                                        |
|                                                              |
|o1 : QuotientRing                                             |
+--------------------------------------------------------------+
|i2 : K1 = koszulComplexDGA(ideal vars R,Variable=>"Y")        |
|                                                              |
|o2 = {Ring => R                          }                    |
|      Underlying algebra => R[Y   ..Y   ]                     |
|                               1,1   1,3                      |
|      Differential => {a, b, c}                               |
|                                                              |
|o2 : DGAlgebra                                                |
+--------------------------------------------------------------+
|i3 : K2 = koszulComplexDGA(ideal {b,c},Variable=>"T")         |
|                                                              |
|o3 = {Ring => R                          }                    |
|      Underlying algebra => R[T   ..T   ]                     |
|                               1,1   1,2                      |
|      Differential => {b, c}                                  |
|                                                              |
|o3 : DGAlgebra                                                |
+--------------------------------------------------------------+
|i4 : g = dgAlgebraMap(K1,K2,matrix{{Y_(1,2),Y_(1,3)}})        |
|                                                              |
|o4 = map (R[Y   ..Y   ], R[T   ..T   ], {Y   , Y   , a, b, c})|
|             1,1   1,3      1,1   1,2     1,2   1,3           |
|                                                              |
|o4 : DGAlgebraMap                                             |
+--------------------------------------------------------------+
|i5 : g' = toComplexMap g                                      |
|                                                              |
|          1             1                                     |
|o5 = 0 : R  <--------- R  : 0                                 |
|               | 1 |                                          |
|                                                              |
|          3                   2                               |
|     1 : R  <--------------- R  : 1                           |
|               {1} | 0 0 |                                    |
|               {1} | 1 0 |                                    |
|               {1} | 0 1 |                                    |
|                                                              |
|          3                 1                                 |
|     2 : R  <------------- R  : 2                             |
|               {2} | 0 |                                      |
|               {2} | 0 |                                      |
|               {2} | 1 |                                      |
|                                                              |
|o5 : ComplexMap                                               |
+--------------------------------------------------------------+

The option EndDegree, must be specified if the source of phi
has any algebra generators of even degree.  The option AssertWellDefined,
is used if one wishes to assert that the result of this
computation is indeed a chain map.  One can construct just the nth map in the
chain map by providing the second ZZ (Macaulay2Doc), parameter.

This function also works when working over different rings, such as the case
when the DGAlgebraMap, is produced via liftToDGMap,
and in the next example.  In this case, the target module is
produced via pushForward (Macaulay2Doc).

+-----------------------------------------------------------------------------+
|i6 : R = ZZ/101[a,b,c]/ideal{a^3,b^3,c^3}                                    |
|                                                                             |
|o6 = R                                                                       |
|                                                                             |
|o6 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i7 : S = R/ideal{a^2*b^2*c^2}                                                |
|                                                                             |
|o7 = S                                                                       |
|                                                                             |
|o7 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i8 : f = map(S,R)                                                            |
|                                                                             |
|o8 = map (S, R, {a, b, c})                                                   |
|                                                                             |
|o8 : RingMap S <-- R                                                         |
+-----------------------------------------------------------------------------+
|i9 : A = acyclicClosure(R,EndDegree=>3)                                      |
|                                                                             |
|o9 = {Ring => R                                        }                     |
|      Underlying algebra => R[T   ..T   ]                                    |
|                               1,1   2,3                                     |
|                                 2       2       2                           |
|      Differential => {a, b, c, a T   , b T   , c T   }                      |
|                                   1,1     1,2     1,3                       |
|                                                                             |
|o9 : DGAlgebra                                                               |
+-----------------------------------------------------------------------------+
|i10 : B = acyclicClosure(S,EndDegree=>3)                                     |
|                                                                             |
|o10 = {Ring => S                                                             |
|       Underlying algebra => S[T   ..T   , T   ..T   , T   ..T   , T   ..T   |
|                                1,1   1,3   2,1   2,4   3,1   3,3   4,1   4,6|
|                                  2       2       2         2 2       2 2    |
|       Differential => {a, b, c, a T   , b T   , c T   , a*b c T   , b c T   |
|                                    1,1     1,2     1,3         1,1       2,1|
|                                                                             |
|o10 : DGAlgebra                                                              |
|-----------------------------------------------------------------------------|
|                                                                             |
|]                                                                            |
|                                                                             |
|    2 2        2 2       2 2            2 2           2 2                    |
|, -a b T   , -a c T   , b c T   T   , -a c T   T   , b c T   T   ,           |
|        2,3        2,2       1,3 2,1        1,3 2,2       1,2 2,1            |
|-----------------------------------------------------------------------------|
|                                    }                                        |
|                                                                             |
|                                                                             |
|  2           2           2                                                  |
|-a T   T   , c T   T   , b T   T   }                                         |
|    1,1 2,4     1,3 2,4     1,2 2,4                                          |
+-----------------------------------------------------------------------------+
|i11 : phi = liftToDGMap(B,A,f)                                               |
|                                                                             |
|o11 = map (S[T   ..T   , T   ..T   , T   ..T   , T   ..T   ], R[T   ..T   ], |
|              1,1   1,3   2,1   2,4   3,1   3,3   4,1   4,6      1,1   2,3   |
|                                                                             |
|o11 : DGAlgebraMap                                                           |
|-----------------------------------------------------------------------------|
|{T   , T   , T   , T   , T   , T   , a, b, c})                               |
|  1,1   1,2   1,3   2,1   2,2   2,3                                          |
+-----------------------------------------------------------------------------+
|i12 : toComplexMap(phi,EndDegree=>3)                                         |
|                                                                             |
|                                          1                                  |
|o12 = 0 : cokernel | a2b2c2 | <--------- R  : 0                              |
|                                 | 1 |                                       |
|                                                                             |
|                                                                    3        |
|      1 : cokernel {1} | a2b2c2 0      0      | <----------------- R  : 1    |
|                   {1} | 0      a2b2c2 0      |    {1} | 1 0 0 |             |
|                   {1} | 0      0      a2b2c2 |    {1} | 0 1 0 |             |
|                                                   {1} | 0 0 1 |             |
|                                                                             |
|                                                                             |
|      2 : cokernel {2} | a2b2c2 0      0      0      0      0      0         |
|                   {2} | 0      a2b2c2 0      0      0      0      0         |
|                   {2} | 0      0      a2b2c2 0      0      0      0         |
|                   {3} | 0      0      0      a2b2c2 0      0      0         |
|                   {3} | 0      0      0      0      a2b2c2 0      0         |
|                   {3} | 0      0      0      0      0      a2b2c2 0         |
|                   {6} | 0      0      0      0      0      0      a2b2c2    |
|                                                                             |
|                                                                             |
|                                                                             |
|      3 : cokernel {3} | a2b2c2 0      0      0      0      0      0         |
|                   {4} | 0      a2b2c2 0      0      0      0      0         |
|                   {4} | 0      0      a2b2c2 0      0      0      0         |
|                   {4} | 0      0      0      a2b2c2 0      0      0         |
|                   {4} | 0      0      0      0      a2b2c2 0      0         |
|                   {4} | 0      0      0      0      0      a2b2c2 0         |
|                   {4} | 0      0      0      0      0      0      a2b2c2    |
|                   {4} | 0      0      0      0      0      0      0         |
|                   {4} | 0      0      0      0      0      0      0         |
|                   {4} | 0      0      0      0      0      0      0         |
|                   {7} | 0      0      0      0      0      0      0         |
|                   {7} | 0      0      0      0      0      0      0         |
|                   {7} | 0      0      0      0      0      0      0         |
|                   {7} | 0      0      0      0      0      0      0         |
|                   {7} | 0      0      0      0      0      0      0         |
|                   {7} | 0      0      0      0      0      0      0         |
|                                                                             |
|                                                                             |
|o12 : ComplexMap                                                             |
|-----------------------------------------------------------------------------|
|                            6                                                |
|| <----------------------- R  : 2                                            |
||    {2} | 1 0 0 0 0 0 |                                                     |
||    {2} | 0 1 0 0 0 0 |                                                     |
||    {2} | 0 0 1 0 0 0 |                                                     |
||    {3} | 0 0 0 1 0 0 |                                                     |
||    {3} | 0 0 0 0 1 0 |                                                     |
||    {3} | 0 0 0 0 0 1 |                                                     |
|     {6} | 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      |             |
|a2b2c2 0      0      0      0      0      0      0      0      |             |
|0      a2b2c2 0      0      0      0      0      0      0      |             |
|0      0      a2b2c2 0      0      0      0      0      0      |             |
|0      0      0      a2b2c2 0      0      0      0      0      |             |
|0      0      0      0      a2b2c2 0      0      0      0      |             |
|0      0      0      0      0      a2b2c2 0      0      0      |             |
|0      0      0      0      0      0      a2b2c2 0      0      |             |
|0      0      0      0      0      0      0      a2b2c2 0      |             |
|0      0      0      0      0      0      0      0      a2b2c2 |             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                  10                                         |
|<------------------------------- R   : 3                                     |
|   {3} | 1 0 0 0 0 0 0 0 0 0 |                                               |
|   {4} | 0 1 0 0 0 0 0 0 0 0 |                                               |
|   {4} | 0 0 1 0 0 0 0 0 0 0 |                                               |
|   {4} | 0 0 0 1 0 0 0 0 0 0 |                                               |
|   {4} | 0 0 0 0 1 0 0 0 0 0 |                                               |
|   {4} | 0 0 0 0 0 1 0 0 0 0 |                                               |
|   {4} | 0 0 0 0 0 0 1 0 0 0 |                                               |
|   {4} | 0 0 0 0 0 0 0 1 0 0 |                                               |
|   {4} | 0 0 0 0 0 0 0 0 1 0 |                                               |
|   {4} | 0 0 0 0 0 0 0 0 0 1 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
|   {7} | 0 0 0 0 0 0 0 0 0 0 |                                               |
+-----------------------------------------------------------------------------+

Ways to use toComplexMap:
=========================

  * "toComplexMap(DGAlgebraMap)"
  * "toComplexMap(DGAlgebraMap,ZZ)"
  * toComplexMap(DGModuleMap) -- Export a
    DG module map to a ComplexMap
  * toComplexMap(DGModuleMap,ZZ), --
    The per-hom-degree component of a DG module map as a matrix

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9060:0.

torAlgebra -- Computes the Tor algebra of a ring
************************************************

  * Usage:
        torR = torAlgebra(R)
  * Inputs:
      * R, a ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * GenDegreeLimit,
        => ..., default value infinity, Maximum homological degree
        searched for Tor-algebra generators
      * RelDegreeLimit,
        => ..., default value infinity, Maximum homological degree
        searched for Tor-algebra relations
  * Outputs:
      * torR, a ring (Macaulay2Doc),

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

+---------------------------------------------------+
|i1 : R = ZZ/101[a,b,c,d]                           |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : TorR = torAlgebra(R)                          |
|                                                   |
|o2 = TorR                                          |
|                                                   |
|o2 : PolynomialRing, 4 skew commutative variable(s)|
+---------------------------------------------------+
|i3 : S = R/ideal{a^3,b^3,c^3,d^5}                  |
|                                                   |
|o3 = S                                             |
|                                                   |
|o3 : QuotientRing                                  |
+---------------------------------------------------+
|i4 : TorS = torAlgebra(S, GenDegreeLimit => 3)     |
|                                                   |
|o4 = TorS                                          |
|                                                   |
|o4 : PolynomialRing, 4 skew commutative variable(s)|
+---------------------------------------------------+

The above example calculates the Tor algebra of R and S up to degree 3, by
default.  One can also specify the maximum degree to compute generators of the
Tor algebra by specifying the GenDegreeLimit option.

+---------------------------------------------------------------+
|i5 : R = ZZ/101[a,b,c,d]/ideal{a^3,b^3,c^3,d^3,a^2*b^2*c^3*d^2}|
|                                                               |
|o5 = R                                                         |
|                                                               |
|o5 : QuotientRing                                              |
+---------------------------------------------------------------+
|i6 : TorR = torAlgebra(R,GenDegreeLimit=>5)                    |
|                                                               |
|o6 = TorR                                                      |
|                                                               |
|o6 : PolynomialRing, 4 skew commutative variable(s)            |
+---------------------------------------------------------------+

Ways to use torAlgebra:
=======================

  * "torAlgebra(Ring)"
  * torAlgebra(Ring,Ring) -- Computes
    Tor_R(S,k) up to a specified generating and relating degree.

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8192:0.

torAlgebra(...,GenDegreeLimit=>...) -- Maximum homological degree searched for Tor-algebra generators
*****************************************************************************************************

  * Usage:
        torAlgebra(..., GenDegreeLimit => n)

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

See GenDegreeLimit.

See also
========

  * torAlgebra -- Computes the Tor algebra of a ring
  * GenDegreeLimit -- Option to bound the homological
    degree searched for algebra generators
  * torAlgebra(...,RelDegreeLimit=>...)
    -- Maximum
    homological degree searched for Tor-algebra relations

Functions with optional argument named GenDegreeLimit:
======================================================

  * findTrivialMasseyOperation(...,GenDegreeLimit=>...),
    --
    Maximum homological degree of generators used in the trivial Massey
    operation search
  * homologyAlgebra(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree searched for homology-algebra generators
  * isGolodHomomorphism(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree of generators used by isGolodHomomorphism
  * isHomologyAlgebraTrivial(...,GenDegreeLimit=>...),
    --
    Maximum homological degree of generators used by isHomologyAlgebraTrivial
  * torAlgebra(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree searched for Tor-algebra generators
  * "torMap(...,GenDegreeLimit=>...)" -- see torMap, -- Compute
    the map of Tor algebras associated to a RingMap.

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

  * Default value: infinity (Macaulay2Doc),
  * Function: torAlgebra, -- Computes the Tor algebra of a
    ring
  * Option key: GenDegreeLimit, -- Option to bound the
    homological degree searched for algebra generators
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9656:0.

torAlgebra(...,RelDegreeLimit=>...) -- Maximum homological degree searched for Tor-algebra relations
****************************************************************************************************

  * Usage:
        torAlgebra(..., RelDegreeLimit => n)

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

See RelDegreeLimit.

See also
========

  * torAlgebra -- Computes the Tor algebra of a ring
  * RelDegreeLimit -- Option to bound the homological
    degree searched for algebra relations
  * torAlgebra(...,GenDegreeLimit=>...)
    -- Maximum
    homological degree searched for Tor-algebra generators

Functions with optional argument named RelDegreeLimit:
======================================================

  * homologyAlgebra(...,RelDegreeLimit=>...)
    -- Maximum
    homological degree searched for homology-algebra relations
  * torAlgebra(...,RelDegreeLimit=>...)
    -- Maximum
    homological degree searched for Tor-algebra relations

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

  * Default value: infinity (Macaulay2Doc),
  * Function: torAlgebra, -- Computes the Tor algebra of a
    ring
  * Option key: RelDegreeLimit, -- Option to bound the
    homological degree searched for algebra relations
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9672:0.

torAlgebra(Ring,Ring) -- Computes Tor_R(S,k) up to a specified generating and relating degree.
**********************************************************************************************

  * Function: torAlgebra,
  * Usage:
        TorRS = torAlgebra(R,S,GenDegreeLimit=>m,RelDegreeLimit=>n)
  * Inputs:
      * R, a ring (Macaulay2Doc),
      * S, a ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * GenDegreeLimit,
        => ..., default value infinity, Maximum homological degree
        searched for Tor-algebra generators
      * RelDegreeLimit,
        => ..., default value infinity, Maximum homological degree
        searched for Tor-algebra relations
  * Outputs:
      * TorRS, a ring (Macaulay2Doc),

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

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c,d]/ideal{a^4,b^4,c^4,d^4}                              |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : M = coker matrix {{a^3*b^3*c^3*d^3}};                                   |
+-----------------------------------------------------------------------------+
|i3 : S = R/ideal{a^3*b^3*c^3*d^3}                                            |
|                                                                             |
|o3 = S                                                                       |
|                                                                             |
|o3 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i4 : HB = torAlgebra(R,S,GenDegreeLimit=>4,RelDegreeLimit=>8)                |
|Finding easy relations           :  -- used 0.72007s (cpu); 0.663292s        |
|                                                                             |
|o4 = HB                                                                      |
|                                                                             |
|o4 : QuotientRing                                                            |
|-----------------------------------------------------------------------------|
|(thread); 0s (gc)                                                            |
+-----------------------------------------------------------------------------+
|i5 : numgens HB                                                              |
|                                                                             |
|o5 = 35                                                                      |
+-----------------------------------------------------------------------------+
|i6 : apply(5,i -> #(flatten entries getBasis(i,HB)))                         |
|                                                                             |
|o6 = {1, 1, 4, 10, 20}                                                       |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : Mres = freeResolution(M, LengthLimit=>8)                                |
|                                                                             |
|      1      1      4      10      20      35      56      84      120       |
|o7 = R  <-- R  <-- R  <-- R   <-- R   <-- R   <-- R   <-- R   <-- R          |
|                                                                             |
|     0      1      2      3       4       5       6       7       8          |
|                                                                             |
|o7 : Complex                                                                 |
+-----------------------------------------------------------------------------+

Note that in this example, $Tor_*^R(S,k)$ has trivial multiplication, since the
map from R to S is a Golod homomorphism by a theorem of Levin and Avramov.

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

  * torAlgebra(Ring,Ring) -- Computes
    Tor_R(S,k) up to a specified generating and relating degree.
-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8218:0.

torMap -- Compute the map of Tor algebras associated to a RingMap.
******************************************************************

  * Usage:
        torPhi = torMap(phi)
  * Inputs:
      * phi, a ring map (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * GenDegreeLimit => ..., default value 3
  * Outputs:
      * torPhi, a ring map (Macaulay2Doc),

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

The functor Tor_R(M,N) is also functorial in the ring argument.  Therefore, a
ring map phi from A to B induces an algebra map from the Tor algebra of A to
the Tor algebra of B.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c]/ideal{a^3,b^3,c^3,a^2*b^2*c^2}                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : S = R/ideal{a*b^2*c^2,a^2*b*c^2,a^2*b^2*c}                              |
|                                                                             |
|o2 = S                                                                       |
|                                                                             |
|o2 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i3 : f = map(S,R)                                                            |
|                                                                             |
|o3 = map (S, R, {a, b, c})                                                   |
|                                                                             |
|o3 : RingMap S <-- R                                                         |
+-----------------------------------------------------------------------------+
|i4 : fTor = torMap(f,GenDegreeLimit=>3)                                      |
|warning: clearing value of symbol T to allow access to subscripted variables |
|       : debug with expression   debug 6944   or with command line option    |
|                                                                             |
|           ZZ            ZZ                                                  |
|o4 = map (---[X ..X  ], ---[X ..X  ], {X , X , X , X , X , X , 0, 0, 0, 0})  |
|          101  1   17   101  1   10     1   2   3   4   5   6                |
|                                                                             |
|              ZZ               ZZ                                            |
|o4 : RingMap ---[X ..X  ] <-- ---[X ..X  ]                                   |
|             101  1   17      101  1   10                                    |
|-----------------------------------------------------------------------------|
| based on it                                                                 |
|--debug 6944                                                                 |
+-----------------------------------------------------------------------------+
|i5 : matrix fTor                                                             |
|                                                                             |
|o5 = | X_1 X_2 X_3 X_4 X_5 X_6 0 0 0 0 |                                     |
|                                                                             |
|              ZZ          1       ZZ          10                             |
|o5 : Matrix (---[X ..X  ])  <-- (---[X ..X  ])                               |
|             101  1   17         101  1   17                                 |
+-----------------------------------------------------------------------------+

In the following example, the map on Tor is surjective, which means that the
ring homomorphism is large (Dress-Kramer).

+-----------------------------------------------------------------------------+
|i6 : R = ZZ/101[a,b,c,d]/ideal{a^3,b^3,c^3,d^3,a*c,a*d,b*c,b*d}              |
|                                                                             |
|o6 = R                                                                       |
|                                                                             |
|o6 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i7 : S = ZZ/101[a,b]/ideal{a^3,b^3}                                          |
|                                                                             |
|o7 = S                                                                       |
|                                                                             |
|o7 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i8 : f = map(S,R,matrix{{a,b,0,0}})                                          |
|                                                                             |
|o8 = map (S, R, {a, b, 0, 0})                                                |
|                                                                             |
|o8 : RingMap S <-- R                                                         |
+-----------------------------------------------------------------------------+
|i9 : fTor = torMap(f,GenDegreeLimit=>4)                                      |
|                                                                             |
|           ZZ           ZZ                                                   |
|o9 = map (---[X ..X ], ---[X ..X  ], {X , X , 0, 0, 0, 0, 0, 0, X , X , 0, 0,|
|          101  1   4   101  1   55     1   2                     3   4       |
|                                                                             |
|              ZZ              ZZ                                             |
|o9 : RingMap ---[X ..X ] <-- ---[X ..X  ]                                    |
|             101  1   4      101  1   55                                     |
|-----------------------------------------------------------------------------|
|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})                          |
+-----------------------------------------------------------------------------+
|i10 : matrix fTor                                                            |
|                                                                             |
|o10 = | X_1 X_2 0 0 0 0 0 0 X_3 X_4 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 |                      |
|                                                                             |
|               ZZ         1       ZZ         55                              |
|o10 : Matrix (---[X ..X ])  <-- (---[X ..X ])                                |
|              101  1   4         101  1   4                                  |
+-----------------------------------------------------------------------------+

Ways to use torMap:
===================

  * "torMap(RingMap)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8727:0.

Verbosity -- Option controlling the verbosity level of DGAlgebras computations
******************************************************************************

  * Usage:
        homologyAlgebra(..., Verbosity => n)
        getGenerators(..., Verbosity => n)

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

Several iterative routines in this package accept a Verbosity option whose
value is a nonnegative integer.  Higher values print more diagnostic output
about the steps being performed (cycle searches, relation searches,
degree-by-degree progress, etc.).  The default value is 0, which suppresses all
progress output.

See also
========

  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.
  * getGenerators -- Cycles whose classes generate the
    homology algebra of a DG algebra

Functions with optional argument named Verbosity:
=================================================

  * getGenerators(...,Verbosity=>...)
    -- Option to control
    progress output from getGenerators
  * homologyAlgebra(...,Verbosity=>...)
    -- Option to control
    progress output from homologyAlgebra
  * icFracP(...,Verbosity=>...) (IntegralClosure)
    -- Prints
    out the conductor element and the number of intermediate modules it
    computed.
  * "idealizer(...,Verbosity=>...)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * integralClosure(...,Verbosity=>...) (IntegralClosure),
    --
    display a certain amount of detail about the computation
  * "isPrime(Ideal,Verbosity=>...)" -- see isPrime(Ideal) (MinimalPrimes),
    -- whether an ideal is prime
  * "makeS2(...,Verbosity=>...)" -- see makeS2 (IntegralClosure),
    -- compute the S2ification of a reduced ring
  * "decompose(Ideal,Verbosity=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,Verbosity=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "ringFromFractions(...,Verbosity=>...)" -- see ringFromFractions (IntegralClosure),
    -- find presentation for f.g. ring

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

The object Verbosity, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:9789:0.

zeroDGModuleMap -- The zero DGModuleMap between two DG modules over a common algebra
************************************************************************************

  * Usage:
        zM = zeroDGModuleMap(N, M)
  * Inputs:
      * N, an instance of the type DGModule,
      * M, an instance of the type DGModule,
  * Outputs:
      * zM, an instance of the type DGModuleMap, The zero
        map M -> N.  Its natural matrix is zero, and its induced map on every
        homology degree is zero.

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

The zero endomorphism is the neutral element for addition and the absorbing
element for composition of DG module maps:

+-----------------------------------------------------------------------+
|i1 : R = ZZ/101[x] / ideal(x^2)                                        |
|                                                                       |
|o1 = R                                                                 |
|                                                                       |
|o1 : QuotientRing                                                      |
+-----------------------------------------------------------------------+
|i2 : A = koszulComplexDGA R                                            |
|                                                                       |
|o2 = {Ring => R                    }                                   |
|      Underlying algebra => R[T   ]                                    |
|                               1,1                                     |
|      Differential => {x}                                              |
|                                                                       |
|o2 : DGAlgebra                                                         |
+-----------------------------------------------------------------------+
|i3 : Mdg = minimalSemifreeResolution(A, R^1 / ideal(x), EndDegree => 2)|
|                                                                       |
|o3 = {Base ring => R                            }                      |
|      DG algebra => R[T   ]                                            |
|                       1,1                                             |
|                                 2                                     |
|      Natural module => (R[T   ])                                      |
|                            1,1                                        |
|      Generator degrees => {{0, 0}, {2, 2}}                            |
|      Differentials on gens => {0, | xT_(1,1) |}                       |
|                                   |     0    |                        |
|                                                                       |
|o3 : DGModule                                                          |
+-----------------------------------------------------------------------+
|i4 : idM = identityDGModuleMap Mdg                                     |
|                                                                       |
|                         2                                             |
|o4 = {Source => (R[T   ])      }                                       |
|                    1,1                                                |
|                         2                                             |
|      Target => (R[T   ])                                              |
|                    1,1                                                |
|      Natural => {0, 0} | 1 0 |                                        |
|                 {2, 2} | 0 1 |                                        |
|                                                                       |
|o4 : DGModuleMap                                                       |
+-----------------------------------------------------------------------+
|i5 : zM  = zeroDGModuleMap(Mdg, Mdg)                                   |
|                                                                       |
|                         2                                             |
|o5 = {Source => (R[T   ]) }                                            |
|                    1,1                                                |
|                         2                                             |
|      Target => (R[T   ])                                              |
|                    1,1                                                |
|      Natural => 0                                                     |
|                                                                       |
|o5 : DGModuleMap                                                       |
+-----------------------------------------------------------------------+
|i6 : idM + zM == idM                                                   |
|                                                                       |
|o6 = true                                                              |
+-----------------------------------------------------------------------+
|i7 : zM * idM == zM                                                    |
|                                                                       |
|o7 = true                                                              |
+-----------------------------------------------------------------------+
|i8 : idM * zM == zM                                                    |
|                                                                       |
|o8 = true                                                              |
+-----------------------------------------------------------------------+

Taking the cokernel of the zero endomorphism recovers the original DG module,
while taking its kernel yields the full module as a DG submodule:

+----------------------------------------+
|i9 : Q = cokernel zM                    |
|                                        |
|o9 = DGQuotientModule Q = M / S         |
|                          2             |
|     Q.natural = (R[T   ])              |
|                     1,1                |
|     Degrees   = {{0, 0}, {2, 2}}       |
|                                        |
|o9 : DGQuotientModule                   |
+----------------------------------------+
|i10 : rank Q.natural == rank Mdg.natural|
|                                        |
|o10 = true                              |
+----------------------------------------+
|i11 : K = kernel zM                     |
|                                        |
|o11 = DGSubmodule of ambient DGModule   |
|      Degrees  => {{0, 0}, {2, 2}}      |
|                           2            |
|      natural  => (R[T   ])             |
|                      1,1               |
|      inclusion => {0, 0} | 1 0 |       |
|                   {2, 2} | 0 1 |       |
|                                        |
|o11 : DGSubmodule                       |
+----------------------------------------+
|i12 : instance(K, DGSubmodule)          |
|                                        |
|o12 = true                              |
+----------------------------------------+

See also
========

  * dgModuleMap -- Construct a DGModuleMap from a matrix or
    from a list of image Vectors
  * identityDGModuleMap -- The identity DGModuleMap
    on a DG module

Ways to use zeroDGModuleMap:
============================

  * "zeroDGModuleMap(DGModule,DGModule)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:436:0.

zerothHomology -- The zeroth homology of a DG algebra as a ring
***************************************************************

  * Usage:
        HA0 = zerothHomology A
  * Inputs:
      * A, an instance of the type DGAlgebra,
  * Outputs:
      * HA0, a ring (Macaulay2Doc), HH_0(A), presented as a
        quotient of A.ring

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

Returns HH_0(A) as a ring, computed by taking A.ring modulo the image of the
degree-one part of the differential.  For a Koszul complex KR =
koszulComplexDGA I over R, this recovers the quotient ring R/I.

+------------------------------------------+
|i1 : Q = ZZ/101[x,y,z]                    |
|                                          |
|o1 = Q                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : I = ideal(x^2, y^2, z^2, x*y*z)      |
|                                          |
|             2   2   2                    |
|o2 = ideal (x , y , z , x*y*z)            |
|                                          |
|o2 : Ideal of Q                           |
+------------------------------------------+
|i3 : KQ = koszulComplexDGA I              |
|                                          |
|o3 = {Ring => Q                          }|
|      Underlying algebra => Q[T   ..T   ] |
|                               1,1   1,4  |
|                        2   2   2         |
|      Differential => {x , y , z , x*y*z} |
|                                          |
|o3 : DGAlgebra                            |
+------------------------------------------+
|i4 : H0 = zerothHomology KQ               |
|                                          |
|o4 = H0                                   |
|                                          |
|o4 : QuotientRing                         |
+------------------------------------------+
|i5 : describe H0                          |
|                                          |
|              Q                           |
|o5 = -------------------                  |
|       2   2   2                          |
|     (z , y , x , x*y*z)                  |
+------------------------------------------+

When A is an acyclic closure, zerothHomology A returns the quotient ring on
which the DG algebra resolves the residue field.

+-----------------------------------------------------------------------------+
|i6 : R = Q / I                                                               |
|                                                                             |
|o6 = R                                                                       |
|                                                                             |
|o6 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i7 : A = acyclicClosure(R, EndDegree => 2)                                   |
|                                                                             |
|o7 = {Ring => R                                                              |
|      Underlying algebra => R[T   ..T   , T   ..T   , T   ..T   ]            |
|                               1,1   1,3   2,1   2,4   3,1   3,3             |
|      Differential => {x, y, z, x*T   , y*T   , z*T   , y*z*T   , y*z*T   ,  |
|                                   1,1     1,2     1,3       1,1       2,1   |
|                                                                             |
|o7 : DGAlgebra                                                               |
|-----------------------------------------------------------------------------|
|                             }                                               |
|                                                                             |
|                                                                             |
|-y*z*T   T   , -y*z*T   T   }                                                |
|      1,1 1,3        1,1 1,2                                                 |
+-----------------------------------------------------------------------------+
|i8 : zerothHomology A                                                        |
|                                                                             |
|      ZZ                                                                     |
|o8 = ---                                                                     |
|     101                                                                     |
|                                                                             |
|o8 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+

See also
========

  * HH DGAlgebra -- The homology algebra of a DG algebra
  * homologyAlgebra -- Compute the homology algebra of
    a DGAlgebra.

Ways to use zerothHomology:
===========================

  * "zerothHomology(DGAlgebra)"

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

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

-------------------------------------------------------------------------------

The source of this document is in DGAlgebras/doc.m2:8875:0.