1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
|
/**************************************************************************
* *
* Regina - A Normal Surface Theory Calculator *
* Computational Engine *
* *
* Copyright (c) 1999-2016, Ben Burton *
* For further details contact Ben Burton (bab@debian.org). *
* *
* This program is free software; you can redistribute it and/or *
* modify it under the terms of the GNU General Public License as *
* published by the Free Software Foundation; either version 2 of the *
* License, or (at your option) any later version. *
* *
* As an exception, when this program is distributed through (i) the *
* App Store by Apple Inc.; (ii) the Mac App Store by Apple Inc.; or *
* (iii) Google Play by Google Inc., then that store may impose any *
* digital rights management, device limits and/or redistribution *
* restrictions that are required by its terms of service. *
* *
* This program is distributed in the hope that it will be useful, but *
* WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
* General Public License for more details. *
* *
* You should have received a copy of the GNU General Public *
* License along with this program; if not, write to the Free *
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, *
* MA 02110-1301, USA. *
* *
**************************************************************************/
/*! \file docs.h
* \brief Contains miscellaneous documentation.
*/
/*! \mainpage
*
* <center><b>
* Regina<br>
* Software for low-dimensional topology<br>
* Copyright © 1999-2016, The Regina development team
* </b></center>
*
* This documentation describes the functions, classes and related
* entities in the C++ calculation engine, as well as how these can
* be accessed through Python.
*
* To start: visit the <a href="modules.html">Modules</a> page and take
* a look around, or browse through the classes regina::Triangulation<3> and
* regina::NormalSurfaces.
*
* <h3>Python</h3>
*
* Although this documentation is written for C++ programmers, Python
* programmers have access to many of the same functions, classes,
* methods and so on. See the special page for \ref pythonapi "Python users"
* for a summary of the differences between C++ and Python, and some of the
* extra features that Python offers.
*
* <h3>Citation</h3>
*
* If you find Regina useful in your research, please consider citing it as
* you would any other paper that you use. A suggested form of reference is:
*
* Benjamin A. Burton, Ryan Budney, William Pettersson, et al.,
* "Regina: Software for low-dimensional topology",
* http://regina-normal.github.io/ , 1999-2016.
*
* <h3>Authors</h3>
*
* The primary developers of Regina are:
* <ul>
* <li>Benjamin Burton <bab@maths.uq.edu.au></li>
* <li>Ryan Budney <rybu@uvic.ca></li>
* <li>William Pettersson <william.pettersson@gmail.com></li>
* </ul>
* <p>
* Many others have been of assistance with this project, be it through
* time, knowledge, testing or code. Please see the full list of
* acknowledgements in the users' handbook.
*
* <h3>Copying and Modification</h3>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* Some of this code comes with additional permissions; see the
* section below regarding online distribution.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
* MA 02110-1301, USA.
*
* <h3>Online Distribution</h3>
*
* Regina's own source code comes with the following permissions in
* addition to the GNU General Public License:
*
* As an exception, when this program is distributed through (i) the
* App Store by Apple Inc.; (ii) the Mac App Store by Apple Inc.; or
* (iii) Google Play by Google Inc., then that store may impose any
* digital rights management, device limits and/or redistribution
* restrictions that are required by its terms of service.
*
* Some third-party libraries included in Regina are not granted this
* exception, and must be removed from any build that is distributed on
* stores that cannot comply with the GNU General Public License (such as
* Apple's App Store). See the third-party licenses below for details.
*
* <h3>SnapPea and SnapPy</h3>
*
* Regina includes portions of the SnapPea kernel and its successor SnapPy,
* which it uses for some geometric calculations. The SnapPea kernel was
* originally written by Jeff Weeks. SnapPy, where this kernel is now
* maintained, is primarily developed by Marc Culler and Nathan Dunfield,
* with contributions from many people. SnapPy and the corresponding
* SnapPea kernel are distributed under the terms of the GNU General Public
* License, version 2 or any later version, as published by the Free Software
* Foundation.
*
* <h3>Normaliz Library</h3>
*
* Regina includes a copy of libnormaliz, which it uses to help with the
* enumeration of fundamental normal surfaces. Normaliz was written by
* Winfried Bruns, Bogdan Ichim and Christof Soeger. It is distributed
* under the terms of the GNU General Public License as published by the
* Free Software Foundation, either version 3 of the License, or (at your
* option) any later version.
*
* <h3>Orb Kernel</h3>
*
* Regina includes snippets of code from Orb, for use in importing and
* exporting files in Orb / Casson format. Orb is based on SnapPea
* (see above) with additional code written by Damian Heard, who has also
* given permission for his code to be distributed under the terms of the
* GNU General Public License.
*/
/*! \page i18n Encodings for international strings
*
* As of version 4.5, Regina (finally) pays attention to character encodings.
*
* The calculation engine uses UTF-8 for all strings (except possibly
* for filenames; see below). This means that programmers who pass
* strings \e into routines must ensure that they use UTF-8, and
* programmers who receive strings \e from routines may assume that
* they are returned in UTF-8. Note that plain ASCII is a subset of
* UTF-8, so plain ASCII text is always fine to use.
*
* Regina's XML data files are also stored using UTF-8. Older
* versions of Regina used LATIN1 (the default for the Qt libraries)
* and did not specify an encoding in the XML header; however, Regina's
* file I/O routines are aware of this, and will convert older data into
* UTF-8 as it is loaded into memory (the files themselves are
* of course not modified). The routine versionUsesUTF8() may be
* useful for programmers who need to work with older data files at a
* low level.
*
* File \e names are a special case, since here Regina must interact with
* the underlying operating system. All filenames that are passed into
* routines must be presented in whatever encoding the operating system
* expects; Regina will simply pass them through to the standard C/C++ file
* I/O routines (such as fopen() or std::ifstream::open()) without modifying
* them in any way.
*
* It should be noted that ancient data files that use the old binary
* format (Regina 2.x, before mid-2002) only support plain ASCII text.
* Support for the old binary format is likely to be removed entirely in the
* very near future.
*
* \ifacespython Users and programmers who use the Python interface must
* take special care, since Python does not pass strings around in UTF-8
* by default.
*
* Proper support for character encodings is quite new, and the main
* author rarely uses this (being a native English speaker). If you
* see Regina treating international characters in unexpected ways,
* please mail the author(s) or file a bug report so the problem can be
* fixed!
*/
/*! \page stddim Standard dimensions
*
* Whilst Regina was originally designed for working with 3-manifolds,
* it now offers varying levels of support for manifolds and triangulations
* in other dimensions.
*
* Regina's <i>standard dimensions</i> are those for which it offers
* rich support (as opposed to basic support).
* For the current release, the <b>standard dimensions are 2, 3 and 4</b>.
*
* This list is expected to grow in future releases.
*/
// Put ourselves in the regina namespace so that automatic links work.
namespace regina {
/*! \page pythonapi Python users
*
* Regina's calculation engine is provided as a shared C++ library, and
* this API documentation describes the native C++ interface for
* working with this library.
*
* Regina also provides a Python module, which wraps many of the
* classes, functions, methods and so on from this library so that
* Python users can access them.
*
* Python users should read this documentation as follows:
*
* - Standard C++ types become native Python types. For example, the C++ type
* \c std::string becomes the native Python string type.
*
* - Everything within the C++ namespace \a regina becomes part of the
* Python module \a regina. For example, the C++ class
* regina::Triangulation<3> becomes the Python class regina.Triangulation3.
*
* - Regina's most important C++ classes and functions are wrapped
* in Python. However, not all classes and functions are wrapped.
* If a class or function is not available in Python then you will
* see a bold <b>Python:</b> note indicating this. See for instance
* the class Bitmask, or the function duplicate().
*
* - Most of Regina's classes and functions have the same interface
* in both C++ and Python, but occasionally there are differences.
* Again, you will see a bold <b>Python:</b> note indicating this.
* See for instance the method Triangulation<3>::tetrahedra(),
* or the global function writeResUsage().
*
* <h3>Testing equality</h3>
*
* It is important to understand how Python's equality tests
* <tt>x == y</tt> and <tt>x is y</tt> operate under Python.
*
* If \a x is a Python variable representing one of Regina's objects, then
* internally \a x stores a reference to one of Regina's native C++ objects.
* Importantly, there may be \e many different Python variables that
* all stores references to the \e same underlying C++ object.
*
* This means that the Python test <tt>x is y</tt> is unreliable.
* If <tt>x is y</tt> returns \c True then certainly \a x and \a y refer to
* the same C++ object; however, if <tt>x is y</tt> returns \c False then
* it is still possible that they refer to the same C++ object.
*
* The solution is to always use the test <tt>x == y</tt>. Regina
* offers three types of classes, and these behave differently under Python:
*
* - Some classes use <i>comparison by value</i>. Here <tt>x == y</tt>
* tests whether the contents of \a x and \a y are mathematically
* equivalent. Examples of such classes are \ref IntegerBase "Integer",
* Rational, and AbelianGroup.
*
* These classes all provide C++ comparison operators == and !=. You
* can read the documentation for these operators to understand
* exactly what mathematical condition(s) are being tested.
*
* - Some classes use <i>comparison by reference</i>. Here <tt>x == y</tt>
* tests whether \a x and \a y refer to the same underlying C++ object.
* This is similar to how the test <tt>x is y</tt> would behave in a
* native Python application. Examples of such classes are
* Triangulation<3> and Tetrahedron<3>.
*
* These classes do not provide C++ comparison operators == or !=.
*
* - Some classes are never instantiated, and so can never be compared
* at all. These classes typically contain only static methods.
* Examples of such classes are Example<dim> and
* \ref regina::i18n::Locale "Locale".
*
* If you wish to find out how a particular class \a C behaves, you can
* examine the attribute <tt>C.equalityType</tt>. This will return one of
* the values \c BY_VALUE, \c BY_REFERENCE or \c NEVER_INSTANTIATED
* respectively:
*
* \code{.unparsed}
* >>> print Triangulation3.equalityType
* BY_REFERENCE
* \endcode
*/
} // namespace regina
|
