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
**/
Generated on Tue Jan 16 2018 22:49:02 for The ChainCon Software (Release 0.03) by
1.8.13