|
The ChainCon Software (Release 0.03)
|
This software is aimed at constructing the chain contraction of a cellular complex, and using this means to compute the homology, cohomology, and related operations on cubical, simplicial or other complexes.
This software is developed for the GNU C++ compiler. The compilation of the library and the programs is relatively intuitive. In the directory into which the source code has been unpacked, one has to run the command make. Although this software uses parts of the CHomP library, all the relevant files have been included in this distribution, so it is not necessary to download or compile it first.
In Linux, all the necessary utilities should be present in the system by default (the GNU C++ compiler and the GNU make). In Windows, one should install them first (e.g. from the MinGW project). In MacOSX, it is recommended to use the GNU C++ compiler instead of the CLANG compiler provided by Apple; therefore, installation of MacPorts, HomeBrew or Fink software may be helpful. For convenience, pre-compiled binary programs for some systems may be provided at the project website.
The main part of this software is provided in terms of a C++ library, programmed as templates of classes and functions for optimal flexibility (so-called generic programming technique). All the header files of which the programming library consists are located in the subdirectory chaincon.
The programs included in this package are more or less complex examples of using the main functions provided as a C++ programming library. These are command-line utilities, to be run from a text terminal window (a.k.a. command prompt). Each program displays brief usage information when called without arguments. The programs read data from files in the text format and display all the results to the output stream, which is the screen by default, but can also be logged to a file using the "--log filename" command-line argument.
The classes defined in the software library are equipped with reading and writing operators that allows the conversion of the data to and from human-readable and intuitive text format. This format is in most part compatible with the CHomP software, and is described below. In particular, any line beginning with the semicolon ';' is treated as a comment and is skipped.
Cubical complexes are defined by listing all the cubical cells line by line, one cell per line. Faces of cells must be either omitted, or listed later than the corresponding cells. A cubical cell is defined as the Cartesian product of intervals of length 1 or 0 (degenerate ones), e.g. [1,2]x[0]x[-3,-2]x[3] (note the brackets, the commas, the letter 'x', and the way of defining degenerate intervals). If the dimension of the cell equals the dimension of the embedding space then it can be defined by listing the minimal coordinates of the vertices, e.g. (1,0,-3,3) (note the parentheses and the commas).
Simplicial complexes are defined by listing all the simplices line by line, one simplex per line. Faces of simplices must be either omitted, or listed later than the corresponding simplices. A simplex is defined as a comma-separated list of numbers of its vertices, e.g. (1,3,18).
Several examples (see below) illustrate how these data formats can be actually used in practice, and also how the provided command-line programs can be used.
Some examples are included in the software package, which may be helpful if one wants to quickly learn how the command-line programs should be used. Processing these examples also gives some hints on the effectiveness of the software, and shows what kind of information it computes. The examples were prepared in such a way that a variety of features can be illustrated. Each example has a description in a text file, and a shell script (a.k.a. batch file) which runs a few commands and displays brief explanations of all the steps. A GUI Python script examples.py has been prepared, which can be used to browse the examples prepared for this piece of software. The list of examples is continually expanding. Contributions of new examples or suggestions are welcome.
This software package is published under the terms of the GNU General Public License, version 3 or any newer version (at the user's choice).
The first version of this software was developed within the framework of the Computational Cohomology project. Since April 1, 2014, the sofware was being developed in the framework of the PHIDM project.
This documentation is currently under construction. Although many classes and functions already have their descriptions, I am aware of the fact that these descriptions are not as detailed as the user might wish to have. Therefore, this documentation has been generated in such a way that it includes the entire source code which sould be consulted if in doubt. The code has many additional comments which shed light on what it actually does.
I am still working on making this documentation more informative and complete, but it takes a lot of time. Therefore, I apologize for any inconvenience caused by the incomplete documentation and I invite to browse the source code instead, or ask me specific questions by email.
Pawel Pilarczyk
1.8.13