## File: docs.h

package info (click to toggle)
regina-normal 5.1-6
• area: main
• in suites: bullseye, buster, sid
• size: 54,488 kB
• sloc: cpp: 142,029; ansic: 19,218; xml: 9,844; objc: 7,729; perl: 1,190; python: 623; sh: 614; makefile: 34
 file content (289 lines) | stat: -rw-r--r-- 13,631 bytes parent folder | download | duplicates (2)
 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289  /************************************************************************** * * * 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 * *
* Regina
* Software for low-dimensional topology
* * 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 Modules page and take * a look around, or browse through the classes regina::Triangulation<3> and * regina::NormalSurfaces. * *

Python

* * 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. * *

Citation

* * 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. * *

Authors

* * The primary developers of Regina are: *
*
• Benjamin Burton <bab@maths.uq.edu.au>
• *
• Ryan Budney <rybu@uvic.ca>
• *
• *
*

* 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. * *

Copying and Modification

* * 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. * *

Online Distribution

* * 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. * *

SnapPea and SnapPy

* * 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. * *

Normaliz Library

* * 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. * *

Orb Kernel

* * It is important to understand how Python's equality tests * x == y and x is y 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 x is y is unreliable. * If x is y returns \c True then certainly \a x and \a y refer to * the same C++ object; however, if x is y returns \c False then * it is still possible that they refer to the same C++ object. * * The solution is to always use the test x == y. Regina * offers three types of classes, and these behave differently under Python: * * - Some classes use comparison by value. Here x == y * 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 comparison by reference. Here x == y * tests whether \a x and \a y refer to the same underlying C++ object. * This is similar to how the test x is y 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 and * \ref regina::i18n::Locale "Locale". * * If you wish to find out how a particular class \a C behaves, you can * examine the attribute C.equalityType. 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