Introduction
What is the role of the &homalg; package in the &homalg; project?
Philosophy

The package &homalg; is meant to be the first part of a continuously growing open source http://www.opensource.org/ multi volume book about homological http://en.wikipedia.org/wiki/Homological_algebra and homotopical algebrahttp://en.wikipedia.org/wiki/Homotopical_algebra. &homalg; is an attempt to translate as much as possible of homological algebra, as can be found in books like , , , , , and , into a language that a computer can directly understand. But just like the aforementioned books, &homalg; should, to a great extent, be readable by a mathematician, even without deep programming knowledge. For the reasons mentioned in (&see; Appendix ) &GAP4; was chosen as the language of &homalg;.

&homalg; provides ...

The package &homalg; is the foundational part of the project. It provides procedures to construct basic objects in homological algebra: rings ring maps matrices modules (generators, relations) maps filtrations complexes (of modules and of complexes) chain maps bicomplexes bigraded (differential) objects spectral sequences functors Beside these so-called constructors &homalg; provides operations to perform computations with these objects. The list of operations includes: resolution of modules computation of subfactor modules applying functors (like Ext, Tor, ...) to modules, maps, complexes and chain maps derivation and composition of functors horse shoe resolution of short exact sequences of modules connecting homomorphisms and long exact sequences Cartan-Eilenberg resolution of complexes hyper (co)homology spectral sequences of bicomplexes the Grothendieck spectral sequences associated to two composable functors test if a module is torsion-free, reflexive, projective, stably free, free, pure determine the rank, codimension, projective dimension, degree of torsion-freeness, and codegree of purity of a module

Using the philosophy of &GAP4;, one or more methods are installed for each operation, depending on properties and attributes of these objects. These properties and attributes can themselves be computed by methods installed for this purpose.

&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; (&see; Appendix ) 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 (&see; ). The above is of course also valid for the column convention.

Rings supported in a sufficient way

Through out this manual the following terminology is used. We say that a computer algebra system sufficiently supports a ring R, if it contains procedures to effectively solve one-sided inhomogeneous linear systems XA=B and AX=B with coefficients over R (&see; ).

Principal limitation

Note that the solution space of the one-sided finite dimensional system YA=0 (resp. AY=0) over a left (resp. right) noetherian ring R is a finitely generated left (resp. right) R-module, even if R is not commutative. The solution space of the linear system X_1 A_1 + A_2 X_2 + A_3 X_3 A_4=0 is in general not an R-module, and worse, in general not finitely generated over the center of R. &homalg; can only handle homological problems that lead to one sided finite dimensional homogeneous or inhomogeneous systems over the underlying ring R. Such problems are called problems of finite type over R. Typically, the computation of Hom(M,N) of two (even) finitely generated modules over a noncommutative ring R is generally not of finite type over R, unless at least one of the two modules is an R-bimodule. Also note that over a commutative ring any linear system can be easily brought to a one-sided form. For more details see .

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.

See also .

&homalg;'s dictionaries (technical)

&homalg; uses the so-called homalgTable, which is stored in the ring, to know how to delegate the necessary matrix operations. I.e. the homalgTable serves as a small dictionary that enables &homalg; to speak (as much as needed of) the language of the computer algebra system which hosts the ring and the matrices. The &GAP; internal ring of integers is the only ring which &homalg; endows with a homalgTable. Other packages like &GaussForHomalg; and &RingsForHomalg; provide dictionaries for further rings. While &GaussForHomalg; defines internal rings and matrices, the package &RingsForHomalg; enables defining external rings and matrices in a wide range of (external) computer algebra systems (&Singular;, &Sage;, &Macaulay2;, &MAGMA;, &Maple;) by providing appropriate dictionaries.

Since these dictionaries are all what is needed to handle matrix operations, &homalg; does not distinguish between handling internal and handling external matrices. Even the physical communication with the external systems is not at all a concern of &homalg;. This is the job of the package &IO_ForHomalg;, which is based on the powerful &IO; package of Max Neunhöffer. Furthermore, for all structures beyond matrices (from relations, generators, and modules, to functors and spectral sequences) &homalg; no longer distinguishes between internal and external.

The advantages of the outsourcing concept

Linking different systems to achieve one task is a highly attractive idea, especially if it helps to avoid reinventing wheels over and over again. This was essential for &homalg;, since &Singular; and &MAGMA; provide the fastest and most advanced Gröbner basis algorithms, while &GAP4; is by far the most convenient programming language to realize complex mathematical structures (&see; Appendix ). Second, the implementation of the homological constructions is automatically universal, since it is independent of where the matrices reside and how the several matrix operations are realized. In particular, &homalg; will always be able to use the system with the fastest Gröbner basis implementation. In this respect is &homalg; and all packages that build upon it future proof.

Does this mean that &homalg; has only algorithms for the generic case?

No, on the contrary. There are a lot of specialized algorithms installed in &homalg;. These algorithms are based on properties and attributes that -- thanks to &GAP4; -- &homalg; objects can carry (&see; Appendix ): Not only can &homalg; take the special nature of the underlying ring into account, it also deals with modules, complexes, ... depending on their special properties. Still, these special algorithms, like all algorithms in &homalg;, are independent of the computer algebra system which hosts the matrices and which will perform the several matrix operations.

The principle of least communication (technical)

Linking different systems can also be highly problematic. The following two points are often among the major sources of difficulties: Different systems use different languages:
It takes a huge amount of time and effort to teach systems the dialects of each others. These dialects are also rarely fixed forever, and might very well be subject to slight modifications. So the larger the dictionary, the more difficult is its maintenance. Data has to be transferred from one system to another:
Even if there is a unified data format, transferring data between systems can lead to performance losses, especially when a big amount of data has to be transferred.

Solving these two difficulties is an important part of &homalg;'s design. &homalg; splits homological computations into two parts. The matrices reside in a system which provides fast matrix operations (addition, multiplication, bases and normal form computations), while the higher structures (modules, maps, complexes, chain maps, spectral sequences, functors, ...) with their properties, attributes, and algorithms live in &GAP4;, as the system where one can easily create such complex structures and handle all their logical dependencies. With this split there is no need to transfer each sort of data outside of its system. The remaining communication between &GAP4; and the system hosting the matrices gets along with a tiny dictionary. Moreover, &GAP4;, as it manages and delegates all computations, also manages the whole data flow, while the other system does not even recognize that it is part of a bidirectional communication.

The existence of such a clear cut is certainly to some extent due to the special nature of homological computations.

Building upon the &homalg; package

As mentioned above, the package &homalg; should only be the first and foundational part of the &homalg; project. On the one hand it is designed independently of the details of the different matrix operations, which other packages are meant to provide. Typically, these packages (like &RingsForHomalg;) heavily rely on existing, well tested, and optimized systems like &Singular;, &Macaulay2;, or &MAGMA;. On the other hand other packages can be built upon or extend the &homalg; package in different ways: add constructors (sheaves, schemes, simplicial sets, ...) add methods for basic operation (Yoneda products, Massey products, Steenrod operations, ...) add methods to compute sheaf cohomology, local cohomology, Hochschild (co)homology, cyclic (co)homology... provide algorithms for holonomic D-modules based on the restriction algorithm: localization, computing tensor products, Hom, Ext, de Rham cohomology, ... support change of rings, Lyndon/Hochschild-Serre spectral sequence, base change spectral sequences, ... support perturbation techniques, Serre and Eilenberg-Moore spectral sequence of simplicial spaces of infinite type, ... ...

The project will remain open and contributions are highly welcome. The different packages will be attributed to their respective authors. The whole project will be attributed to the "&homalg; team", i.e. the authors and contributers of all packages in the project.

Frequently asked questions
Q: Does outsourcing the matrices mean that &homalg; is able to compute spectral sequences, for example, without ever seeing the matrices involved in the computation?
A: Yes.
Q: Can &homalg; profit from the implementation of homological constructions like Hom, Ext, ... in &Singular;?
A: No. This is for a lot of reasons incompatible with the idea and design (&see; ) of &homalg;.
Q: Are the external systems involved in the higher algorithms?
A: No. They host all the matrices and do all matrix operations delegated to them without knowing what for. The meaning of the matrices and their logical interrelation is only known to &GAP4;.
Q: Do developers of packages building upon &homalg; need to know anything about the communication with the external systems?
A: No, unless they want to use more features of the external systems than those reflected by &homalg;. For this purpose, developers can use the unified communication interface provideb by &HomalgToCAS;. This is the interface used by &homalg;.
This manual

Chapter describes the installation of this package, while Chapter provides a short quick guide to build your first own example, using the package &ExamplesForHomalg;. The remaining chapters are each devoted to one of the &homalg; objects (&see; ) with its constructors, properties, attributes, and operations.