The ChainCon Software (Release 0.03)
mainpage.h
Go to the documentation of this file.
1 /////////////////////////////////////////////////////////////////////////////
2 ///
3 /// \file
4 ///
5 /// The main page for the source code documentation.
6 ///
7 /////////////////////////////////////////////////////////////////////////////
8 
9 // Copyright (C) 2009-2016 by Pawel Pilarczyk.
10 //
11 // This file is part of my research software package. This is free software:
12 // you can redistribute it and/or modify it under the terms of the GNU
13 // General Public License as published by the Free Software Foundation,
14 // either version 3 of the License, or (at your option) any later version.
15 //
16 // This software is distributed in the hope that it will be useful,
17 // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 // GNU General Public License for more details.
20 //
21 // You should have received a copy of the GNU General Public License
22 // along with this software; see the file "license.txt". If not,
23 // please, see <http://www.gnu.org/licenses/>.
24 
25 /**
26 
27 \mainpage
28 
29 
30 \section intro Introduction
31 
32 This software is aimed at constructing the chain contraction
33 of a cellular complex, and using this means to compute
34 the homology, cohomology, and related operations
35 on cubical, simplicial or other complexes.
36 
37 
38 \section compilation Compilation
39 
40 This software is developed for the GNU C++ compiler.
41 The compilation of the library and the programs is relatively intuitive.
42 In the directory into which the source code has been unpacked,
43 one has to run the command <em>make</em>.
44 Although this software uses parts of
45 the <a href="http://chomp.rutgers.edu/software/">CHomP library</a>,
46 all the relevant files have been included in this distribution,
47 so it is not necessary to download or compile it first.
48 
49 In Linux, all the necessary utilities
50 should be present in the system by default
51 (the GNU C++ compiler and the GNU make).
52 In Windows, one should install them first (e.g. from the
53 <a href="http://www.mingw.org/">MinGW</a> project).
54 In MacOSX, it is recommended to use the GNU C++ compiler
55 instead of the CLANG compiler provided by Apple;
56 therefore, installation of
57 <a href="https://www.macports.org/">MacPorts</a>,
58 <a href="http://brew.sh/">HomeBrew</a>
59 or <a href="http://www.finkproject.org/">Fink</a> software may be helpful.
60 For convenience, pre-compiled binary programs for some systems
61 may be provided at the project website.
62 
63 
64 \section library Software Library
65 
66 The main part of this software is provided in terms
67 of a C++ library, programmed as templates of classes
68 and functions for optimal flexibility
69 (so-called generic programming technique).
70 All the header files of which the programming library consists
71 are located in the subdirectory <em>chaincon</em>.
72 
73 
74 \section programs Programs
75 
76 The programs included in this package are more or less complex
77 examples of using the main functions
78 provided as a C++ programming library.
79 These are command-line utilities, to be run from a text terminal window
80 (a.k.a. command prompt).
81 Each program displays brief usage information
82 when called without arguments.
83 The programs read data from files in the text format
84 and display all the results to the output stream,
85 which is the screen by default,
86 but can also be logged to a file using the "--log filename"
87 command-line argument.
88 
89 
90 \section data Data Formats
91 
92 The classes defined in the software library
93 are equipped with reading and writing operators
94 that allows the conversion of the data to and from
95 human-readable and intuitive text format.
96 This format is in most part compatible
97 with the CHomP software, and is described below.
98 In particular, any line beginning with the semicolon ';'
99 is treated as a comment and is skipped.
100 
101 <b>Cubical complexes</b> are defined by listing all the cubical cells
102 line by line, one cell per line.
103 Faces of cells must be either omitted,
104 or listed later than the corresponding cells.
105 A cubical cell is defined as the Cartesian product
106 of intervals of length 1 or 0 (degenerate ones),
107 e.g. <em>[1,2]x[0]x[-3,-2]x[3]</em> (note the brackets,
108 the commas, the letter 'x', and the way of defining degenerate intervals).
109 If the dimension of the cell equals the dimension
110 of the embedding space then it can be defined
111 by listing the minimal coordinates of the vertices,
112 e.g. <em>(1,0,-3,3)</em> (note the parentheses and the commas).
113 
114 <b>Simplicial complexes</b> are defined by listing all the simplices
115 line by line, one simplex per line.
116 Faces of simplices must be either omitted,
117 or listed later than the corresponding simplices.
118 A simplex is defined as a comma-separated list of numbers of its vertices,
119 e.g. <em>(1,3,18)</em>.
120 
121 Several examples (see below) illustrate how these data formats
122 can be actually used in practice, and also how the provided
123 command-line programs can be used.
124 
125 
126 \section examples Examples
127 
128 Some examples are included in the software package,
129 which may be helpful if one wants to quickly learn
130 how the command-line programs should be used.
131 Processing these examples also gives some hints on the effectiveness
132 of the software, and shows what kind of information it computes.
133 The examples were prepared in such a way that a variety of features
134 can be illustrated.
135 Each example has a description in a text file,
136 and a shell script (a.k.a. batch file)
137 which runs a few commands and displays brief explanations of all the steps.
138 A GUI Python script <em>examples.py</em> has been prepared,
139 which can be used to browse the examples
140 prepared for this piece of software.
141 The list of examples is continually expanding.
142 Contributions of new examples or suggestions are welcome.
143 
144 
145 \section license License
146 
147 This software package is published under the terms
148 of the <a href="http://www.gnu.org/licenses/gpl.html">GNU
149 General Public License, version 3</a>
150 or any newer version (at the user's choice).
151 
152 
153 \section ackn Acknowledgments
154 
155 The first version of this software was developed within the framework of the
156 <a href="http://www.pawelpilarczyk.com/cohomology/">Computational
157 Cohomology</a> project.
158 Since April 1, 2014, the sofware was being developed
159 in the framework of the
160 <a href="http://www.pawelpilarczyk.com/phidm/">PHIDM</a> project.
161 
162 
163 \section remark Remarks
164 
165 This documentation is currently under construction.
166 Although many classes and functions already have their descriptions,
167 I am aware of the fact that these descriptions are not as detailed
168 as the user might wish to have. Therefore, this documentation
169 has been generated in such a way that it includes the entire source code
170 which sould be consulted if in doubt. The code has many additional
171 comments which shed light on what it actually does.
172 
173 I am still working on making this documentation more informative
174 and complete, but it takes a lot of time.
175 Therefore, I apologize for any inconvenience caused by the incomplete
176 documentation and I invite to browse the source code instead,
177 or ask me specific questions by email.
178 
179 Pawel Pilarczyk
180 
181 **/