      submodule
      Copyright (c)  2005-2013 John Abbott, Anna M. Bigatti
      GNU Free Documentation License, Version 1.2
%!includeconf: ../aux-txt2tags/config.t2t
      TeXTitle{submodule}{John Abbott, Anna M. Bigatti}



== Examples ==[examples]
%----------------------------------------------------------------------
- [ex-module2.C ../../examples/index.html#ex-module2.C]
-

== User documentation ==
%======================================================================

Here are some pseudo-constructors for modules which are generated by 
a (finite) vector of [[ModuleElem]] (in a [[FreeModule]]).
There is no class for submodules, they are objects of type [[FGModule]].

There are several ways to create a submodule:

- ``submodule(M, gens)`` --
    creates an [[FGModule]] representing the submodule of
    the FGModule M generated by the elements in gens; note that M must
    be specified even though it is usually implicit in the values
    contained in gens (unless gens is empty).
- ``SubmoduleCols(M, A)`` --
    the submodule generated by the columns of the [[matrix]] ``A``.
- ``SubmoduleRows(M, A)`` --
    the submodule generated by the rows of the [[matrix]] ``A``.
-


=== Operations ===[operations]

The permitted operations on submodules are:
```
  FGModule SyzOfGens(const FreeModule& F, const ideal& I);
  FGModule SyzOfGens(const FreeModule& F, const FGModule& N);
  FGModule SyzOfGens(const ideal& I);
  FGModule SyzOfGens(const FGModule& N);
  bool IsElem(const ModuleElem& v, const module& M);
  bool IsContained(const module& M, const module& M);
```

== Maintainer documentation for the classes module, and ModuleElem ==
%======================================================================

I shall suppose that the maintainer documentation for modules and
FGModules has already been read and digested.  It could also be helpful
to have read ring.txt since the "design philosophy" here imitates that
used for rings.



SubmoduleImpl is a concrete class derived from FGModuleBase,
i.e. objects of this class represent submodules of explicitly finitely
generated modules.  The data members comprise the two obvious values:
```
  FreeModule myM;                 // the ambient module in which the generators live
  vector<ModuleElem> myGensArray; // the generators as specified by the user
```

Additionally there are two other data members:
```
  bool myTidyGensIsValid;             // true iff myTidyGensArray contains a correct value
  vector<ModuleElem> myTidyGensArray; // a "nice" set of generators
```

It is difficult to be precise about the value which myTidyGensArray
should contain (when valid) since it depends upon the module.  If the
module is over a polynomial ring then it will be a Groebner basis.  If
the module is over Z then it will presumably be either a "Hermite Basis"
or an "LLL Basis".


== Bugs, Shortcomings and other ideas ==
%======================================================================

Implementation and documentation are rather incomplete.

Why is myM a FreeModule and not an FGModule???

What is myTidyGensArray for a module over Z???

