--- status: Draft
--- author(s): MES
--- notes: 

doc ///
Node
  Key
    Hom
   (Hom, Ring, Ring)
   (Hom, Ring, Ideal)
   (Hom, Ring, Module)
   (Hom, Ideal, Ring)
   (Hom, Ideal, Ideal)
   (Hom, Ideal, Module)
   (Hom, Module, Ring)
   (Hom, Module, Ideal)
   (Hom, Module, Module)
   [Hom, DegreeLimit]
   [Hom, MinimalGenerators]
   [Hom, Strategy]
  Headline
    module of homomorphisms
  Usage
    Hom(M, N)
  Inputs
    M:{Ring,Ideal,Module}
    N:{Ring,Ideal,Module}
    DegreeLimit => {ZZ,List}
      if set, stop after homomorphisms in this degree have been computed
    MinimalGenerators => Boolean
      whether to @TO trim@ the resulting module
    Strategy => Thing
  Outputs
    :Module
      isomorphic to $\mathrm{Hom}_R(M,N), where $M$ and $N$ are both $R$-modules
  Description
    Text
      If $M$ or $N$ is an ideal or ring, it is regarded as a module in the evident way.
    Example
      R = QQ[x,y]/(y^2 - x^3);
      M = image matrix{{x, y}}
      H = Hom(M, M, MinimalGenerators => true)
    Text
      To recover the modules used to create a Hom-module, use the function @TO formation@.
    Example
      formation H
    Text
      Specific homomorphisms may be obtained using @TO homomorphism@, as follows.
    Example
      f0 = homomorphism H_{0}
      f1 = homomorphism H_{1}
    Text
      In the example above, @TT "f0"@ is the identity map, and @TT "f1"@ maps $x$ to $y$ and $y$ to $x^2$.
    Example
      M_0, M_1
      f0 M_0, f0 M_1
      f1 M_0, f1 M_1
  Contributors
    Devlin Mallory implemented the strategy which accepts a degree limit.
  SeeAlso
    Ext
    formation
  Subnodes
    adjoint
    compose
    homomorphism
    homomorphism'
    (Hom, Module, Matrix)

Node
  Key
   (Hom, Module, Matrix)
   (Hom, Matrix, Module)
   (Hom, Matrix, Matrix)
  Headline
    induced map on Hom
  Synopsis
    Usage
      Hom(f,g)
    Inputs
      f:Matrix
      g:Matrix
      DegreeLimit => {ZZ,List}
        see @TO [Hom, DegreeLimit]@
      MinimalGenerators => Boolean
        see @TO [Hom, MinimalGenerators]@
      Strategy => Thing
        see @TO [Hom, Strategy]@
    Outputs
       :Matrix
        the map on Hom induced by the maps $f$ and $g$
  Synopsis
    Usage
      Hom(f,M)
      Hom(M,f)
    Inputs
      f:Matrix
      M:Module
      DegreeLimit => {ZZ,List}
        see @TO [Hom, DegreeLimit]@
      MinimalGenerators => Boolean
        see @TO [Hom, MinimalGenerators]@
      Strategy => Thing
        see @TO [Hom, Strategy]@
    Outputs
       :Matrix
        the map on Hom induced by the map $f$
    Description
      Example
        R = QQ[x]
	f = vars R
	M = image f
	g = Hom(f,M)
	target g
	source g
      Example
        R = QQ[x]
	f = vars R
	M = image f
	g = Hom(M,f)
	target g
	source g
  SeeAlso
    inducedMap

Node
  Key
   (Hom, Module, ChainComplex)
   (Hom, ChainComplex, Module)
   (Hom, Module, ChainComplexMap)
   (Hom, ChainComplexMap, Module)
  Headline
    the Hom functor
  Usage
    Hom(M, C)
    Hom(C, M)
  Inputs
    M:Module
    C:ChainComplex
    DegreeLimit => {ZZ,List}
      see @TO [Hom, DegreeLimit]@
    MinimalGenerators => Boolean
      see @TO [Hom, MinimalGenerators]@
    Strategy => Thing
      see @TO [Hom, Strategy]@
  Outputs
    :ChainComplex
      the chain complex whose $i$-th spot is $\mathrm{Hom}(M, C_i)$,
      in the first case, or $\mathrm{Hom}(C_(-i), M)$ in the second case.
  Description
    Example
      R = QQ[a..d];
      C = res coker vars R
      M = R^1/(a,b)
      C' = Hom(C,M)
      C'.dd_-1
      C'.dd^2 == 0
  Synopsis
    Heading
      induced map on Hom
    Usage
      Hom(f,M)
      Hom(M,f)
    Inputs
      f:ChainComplexMap
      M:Module
      DegreeLimit => {ZZ,List}
        see @TO [Hom, DegreeLimit]@
      MinimalGenerators => Boolean
        see @TO [Hom, MinimalGenerators]@
      Strategy => Thing
        see @TO [Hom, Strategy]@
    Outputs
       :ChainComplexMap
         the induced map on Hom
  Caveat
    See @TO "Complexes :: Hom(Complex,Complex)"@ for Hom of two chain complexes.
  SeeAlso
    resolution
///

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

doc ///
Node
  Key
    End
   [End, DegreeLimit]
   [End, MinimalGenerators]
   [End, Strategy]
  Headline
    module of endomorphisms
  Usage
    End M
  Inputs
    M:{Ring,Ideal,Module,ChainComplex}
    DegreeLimit => {ZZ,List}
      see @TO [Hom, DegreeLimit]@
    MinimalGenerators => Boolean
      see @TO [Hom, MinimalGenerators]@
    Strategy => Thing
      see @TO [Hom, Strategy]@
  Description
    Text
      Constructs the module of endomorphisms of $M$.
    Example
      R = QQ[a,b,c];
      M = coker koszul_2 vars R
      End M
  SourceCode
    End
///

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

doc ///
Node
  Key
    reshape
   (reshape, Module, Module, Matrix)
  Headline
    reshape a matrix
  Usage
    reshape(F, G, f)
  Inputs
    F:Module -- a free module
    G:Module -- a free module
    f:Matrix
  Outputs
     :Matrix
       @TT "F <-- G"@ obtained from @TT "f"@ by taking elements from the first column of @TT "f"@,
       then the second, and so on, filling them into the result column by column.
  Description
    Text
      Currently, it is assumed that @TT "f"@ and the result both have the same number of entries.
      The resulting map has the same degree that @TT "f"@ has, but it is easy to spoil homogeneity
      by giving incorrect free modules.
    Example
      f = matrix{{1,3,5,7,9,11},{2,4,6,8,10,12}}
      reshape(ZZ^3,ZZ^4,f)
///

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

doc ///
Node
  Key
    adjoint
   (adjoint, Matrix, Module, Module)
    adjoint'
   (adjoint', Matrix, Module, Module)
  Headline
    the tensor-Hom adjunction maps
  Description
    Text
      Recall that @TO (tensor, Module, Module)@ and @TO (Hom, Module, Module)@ form an adjoint pair,
      meaning that there is a natural isomorphism
      $$ \mathrm{Hom}(F\otimes G,H) \cong \mathrm{Hom}(F,\mathrm{Hom}(G,H)). $$
  Synopsis
    Usage
      adjoint(f, F, G)
    Inputs
      f:Matrix
        a homomorphism $F \otimes G \to H$
      F:Module -- a free module
      G:Module -- a free module
    Outputs
       :Matrix
         the adjoint homomorphism $F \to \mathrm{Hom}(G,H)$
    Description
      Example
        R = QQ[x_1 .. x_24];
	f = genericMatrix(R, 2, 4*3)
	isHomogeneous f
	g = adjoint(f, R^4, R^3)
      Text
        If @TT "f"@ is homogeneous, and @TT "source f === F ** G"@ (including the grading),
	then the resulting matrix will be homogeneous.
      Example
        g = adjoint(f, R^4, R^{-1,-1,-1})
	isHomogeneous g
        f === adjoint'(g, R^{-1,-1,-1}, R^2)
  Synopsis
    Usage
      adjoint'(g, G, H)
    Inputs
      g:Matrix
        a homomorphism $F \to \mathrm{Hom}(G,H)$ between modules
      G:Module -- a free module
      H:Module -- a free module
    Outputs
       :Matrix
         the adjoint homomorphism $F \otimes G \to H$
    Description
      Text
        If @TT "g"@ is homogeneous, and @TT "target g === Hom(G,H)"@ (including the grading),
	then the resulting matrix will be homogeneous.
      Example
        R = QQ[x_1 .. x_12];
        g = genericMatrix(R, 6, 2)
        f = adjoint'(g, R^2, R^3)
        isHomogeneous f
        g === adjoint(f, R^{-1,-1}, R^2)
  SeeAlso
    dual
    flip
    compose
    reshape
    (Hom, Module, Module)
    (tensor, Module, Module)
///

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

doc ///
Node
  Key
    homomorphism
   (homomorphism, Matrix)
  Headline
    get the homomorphism from element of Hom
  Usage
    homomorphism f
  Inputs
    f:Matrix
      corresponding to a map $R^1 \to \mathrm{Hom}(M,N)$
  Outputs
    :Matrix
      the map $M \to N$, corresponding to the element $f \in \mathrm{Hom}(M,N)$
  Description
    Text
      When @TT "H = Hom(M,N)"@ is computed, information about computing the morphisms
      corresponding to its elements is stored in @TT "H"@.
    Example
      R = QQ[x,y,z, Degrees => {2,3,1}]/(y^2 - x^3)
      H = Hom(ideal(x,y), R^1)
      f = H_{1}
      g = homomorphism f
    Text
      The source and target are what they should be.
    Example
      source g === module ideal(x,y)
      target g === R^1
    Text
      Except for a possible redistribution of degrees between the map and modules,
      we can undo the process with @TO "homomorphism'"@.
    Example
      f' = homomorphism' g
      f === f'
      f - f'
      degree f, degree f'
      degrees f, degrees f'
    Text
      After @TO2((minimalPresentation, Module), "pruning")@ a Hom module,
      one cannot use homomorphism directly. Instead, first apply the pruning map:
    Example
      H1 = prune H
      homomorphism(H1.cache.pruningMap * H1_{1})
  SeeAlso
    Hom
    homomorphism'

Node
  Key
    homomorphism'
   (homomorphism', Matrix)
   [homomorphism', DegreeLimit]
   [homomorphism', MinimalGenerators]
   [homomorphism', Strategy]
  Headline
    get the element of Hom from a homomorphism
  Usage
    homomorphism' f
  Inputs
    f:Matrix
      of the form $M \to N$
    DegreeLimit => {ZZ,List}
      see @TO [Hom, DegreeLimit]@
    MinimalGenerators => Boolean
      see @TO [Hom, MinimalGenerators]@
    Strategy => Thing
      see @TO [Hom, Strategy]@
  Outputs
     :Matrix
       the map $R^1 \to \mathrm{Hom}(M,N)$, corresponding to the map $f \in \mathrm{Hom}(M,N)$
  Description
    Example
      R = QQ[x,y,z]
      f = vars R ++ vars R
      g = homomorphism' f
      target g === Hom(source f, target f)
    Text
      We can undo the process with @TO homomorphism@.
    Example
      f' = homomorphism g
      f === f'
  SourceCode
    (homomorphism', Matrix)
  SeeAlso
    Hom
    homomorphism
    adjoint
///

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

doc ///
Node
  Key
     compose
    (compose, Module, Module, Module)
   [(compose, Module, Module, Module), DegreeLimit]
   [(compose, Module, Module, Module), MinimalGenerators]
   [(compose, Module, Module, Module), Strategy]
  Headline
    composition as a pairing on Hom-modules
  Usage
    compose(M, N, P)
  Inputs
    M:Module
    N:Module
    P:Module
--    DegreeLimit => {ZZ,List}
--      see @TO [Hom, DegreeLimit]@
--    MinimalGenerators => Boolean
--      see @TO [Hom, MinimalGenerators]@
--    Strategy => Thing
--      see @TO [Hom, Strategy]@
  Outputs
    :Matrix
      the composition map of homomorphism modules $\mathrm{Hom}(M,N)$ and $\mathrm{Hom}(N,P)$
  Description
    Text
      In the following example we check that the map does implement the composition map
      $$ \mathrm{Hom}(M,N) \otimes \mathrm{Hom}(N,P) \to \mathrm{Hom}(M,P). $$
    Example
      R = QQ[x,y]
      M = image vars R ++ R^2
      f = compose(M,M,M);
      H = Hom(M,M);
      g = H_{0}
      h = homomorphism g
      f * (g ** g)
      h' = homomorphism oo
      h' === h * h
      assert oo
    Text
      The modules should be defined over the same ring.
  SeeAlso
    Hom
    homomorphism
    homomorphism'
    adjoint
    flip
///
