Introduction
What is the role of the &MatricesForHomalg; package in the &homalg; project? &MatricesForHomalg; provides ... The package &MatricesForHomalg; provides: rings ring elements ring maps matrices &homalg; delegates ... The package &homalg; delegates all matrix operations as it treats matrices and their rings as black boxes. &homalg; comes with a single predefined class of rings and a single predefined class of matrices over these rings -- the so-called internal matrices (&see; ) over so-called internal rings (&see; ). An internal matrix (resp. ring) is simply a wrapper containing a &GAP;-builtin matrix (resp. ring). &homalg; allows other packages to define further classes or extend existing classes of rings and matrices together with their operations. For example: The &homalg; subpackage &ResidueClassRingForHomalg; (&see; Appendix ) defines the classes of residue class rings, residue class ring elements, and matrices over residue class rings. Such a matrix is defined by a matrix over the ambient ring which is nevertheless interpreted modulo the ring relations, i.e. modulo the generators of the defining ideal. The package &GaussForHomalg; extends the class of internal matrices enabling it to wrap sparse matrices provided by the package &Gauss;. &GaussForHomalg; delegates the essential part of the matrix creation and all matrix operations to &Gauss;. The package &HomalgToCAS; defines the classes of so-called external rings and matrices and the package &RingsForHomalg; delegates the essential part of the matrix creation and all matrix operations to external computer algebra systems like &Singular;, &Macaulay2;, &Sage;, &Macaulay2;, &MAGMA;, &Maple;, ... . The package &homalg; accesses external matrices via pointers. The pointer of an external matrix is simply its name in the external system. &HomalgToCAS; chooses these names. The package &LocalizeRingForHomalg; defines the classes of local(ized) rings, local ring elements, and local matrices. A &homalg; local matrix contains a &homalg; matrix as a numerator and an element of the global ring as a denominator.

The matrix operations are divided into two classes called Tools and Basic. The Tools operations include addition, subtraction, multiplication, extracting certain rows or columns, stacking, and augmenting matrices (&see; Appendix ). The Basic operations include the two basic operations in linear algebra needed to solve an inhomogeneous linear system XA=B with coefficients in a not necessarily commutative ring R (&see; Appendix ): Effectively reducing B modulo A, i.e. effectively deciding if a row (or a set of rows) B lies in the R-span of the rows of the matrix A. Computing an R-generating set of row syzygies (=R-relations among the rows) of A, i.e. computing an R-generating set of the left kernel of A. This generating set is then given as the rows of a matrix Y and YA=0. The first operation is nothing but deciding the solvability of the inhomogeneous system XA=B and if solvable to compute a particular solution X, while the second is to compute an R-generating set for the homogeneous solution space, i.e. the solution space of the homogeneous system YA=0. The above is of course also valid for the column convention. The black box concept

Now we address the following concerns: Wouldn't the idea of using algorithms like the Gröbnerbasis algorithm(s) as a black box (&see; ) contradict the following facts? It is known that an efficient Gröbnerbasis algorithm depends on the ring R under consideration. For example the implementation of the algorithm depends on the ground ring (or field) k. Often enough highly specialized implementations are used to address specific types of linear systems of equations (occuring in specific homological problems) in order to increase the speed or reduce the space needed for the computations. The following should clarify the above concerns. Since each ring comes with its own black box, the first point is automatically resolved. Allow the black box coming with each ring to contain the different available implementations and make them accessible to &homalg; via standarized names, independent of the computer algebra system used to perform computations.
This manual Chapter describes the installation of this package. The remaining chapters are each devoted to one of the &MatricesForHomalg; objects (&see; ) with its constructors, properties, attributes, and operations.