Welcome to pygsl’s documentation!¶
Buidling and installing PyGSL¶
Front Matter¶
Copyright © 2002,2005,2017 The pygsl Team.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in section gun-free-doc entitled “GNU Free Documentation License”.
System Requirements, Installation¶
Status of GSL-Library¶
The gsl-library is since version 1.0 stable and for general use. More information about it at http://www.gnu.org/software/gsl/.
Status of this interface¶
Nearly all modules are wrapped. A lot of tests are covering various functionality. Please report to the pygsl-discuss mailing list if you find a bug.
The hankel modules have been wrapped. Please write to the mailing list pygsl-discuss if you require one of the modules and are willing to help with a simple example. If any other function is missing or some other module (e.g. ntuple) or function, do not hesitate to write to the list.
Retriving the Interface¶
You can download it here: http://sourceforge.net/projects/pygsl
Requirements¶
- To build the interface, you will need
gsl-1.x or gsl-2.1 or newer http://www.gnu.org/software/gsl/
python2.7 or python3.x,
numpy http://numpy.sf.net
a c compiler like gcc
- Supported Platforms are:
Linux (Redhat/Debian/SuSE) with python2.* and gsl-1.*
Win32
MacOS X
But is is supposed to build on any POSIX platforms.
Installing the pygsl interface¶
The gsl-config must be on your path on posix platforms. Then type:
# unpack the source distribution
gzip -d -c pygsl-x.y.z.tar.gz|tar xvf-
cd pygsl-x.y.z
# do this with your prefered python version
# to set the gsl location explicitly use setup.py --gsl-prefix=/path/to/gsl
# First configure pygsl interface
python setup.py config
#
python setup.py build
# change to an user id, that is allowed to do installation
python setup.py install
Ready….
Do not test the interface in the distribution root In this case
python will search for all modules in the distribution directory pygsl.
If you find unresolved symbols later on, delete the C source in the swig_src files. Check that swig can be called from the command line. Then start the build process again.
In this case swig will rebuild the C files. The swig_src files distributed with pygsl are to an up to date version of GSL (2.4 as of this writing). Swig parses partly some header header files and builds the appropriate interface functions. If you have an older GSL version locally installed, the sources in the swig_src directory can contain links to symbols which are not defined by the locally installed GSL version.
Building on win32¶
Windows by default does not allow to run a posix shell. Here a different path is required. First change into the directory gsl_dist. Copy the file and edit it to reflect your installation of GSL and SWIG if you want to run it yourself. The pygsl windows binaries distributed over http://sourceforge.net/projects/pygsl/ are built using the mingw compiler.
Building the GSL library¶
In a first step install Msys http://www.msys2.org/ .
Execute the commands given in the shell
script below (it is also given in doc/win/pygsl_msys2_prepare.sh
or can be dowloaded here):
#!/bin/sh
# It can be that you have to make python ready for handling msys2
# # python handling of the Microsoft C libary msvcr
# # needs to be handled by
# pacman -S patch
# # Do I need that ... if I hack on numpy
# # Some patch for msvcr
# # Now put into two patches
# wget.exe https://bugs.python.org/file40608/patch.diff
# cd /c/LocalPrograms/Python36/Lib/distutils
# patch -p0 < /c/Users/mfp/Devel/patch.diff
# Make sure that the build system is installed
pacman -S make
pacman -S mingw-w64-x86_64-gcc
pacman -S mingw-w64-x86_64-lld
pacman -S tar
# A build directory
mkdir Devel
# A directory to install the GSL library to
mkdir local
# The location of the tar balls.
GSL_DIST_FILE=`pwd`/Downloads/gsl-2.3.tar.gz
PyGSL_DIST_FILE=`pwd`/Downloads/pygsl-2.2.0.tar.gz
# I assume that GSL has to be built. lets get started
cd Devel
tar zxvf "$GSL_DIST_FILE"
pushd gsl-2.3/
# include the gcc path ...
# if one uses the environment variable CC the configure script does not
export PATH=$PATH:/mingw64/bin
./configure --enable-shared=no --disable-shared --prefix=`pwd`/../../local/
make
make install
popd
# Assuming that it has been successful!
$ tar zxvf "$PyGSL_DIST_FILE"
echo "pygsl is now built using pygsl_windows_compile.bat"
echo "Start it from the command shell!"
This will build gsl using the mingw compiler.
Building the pygsl interface¶
Copy the file
gsl_dist/gsl_site_example.py to
gsl_dist/gsl_site.py. Edit it so that it reflects your
installation.
Now open a windows command shell. An example batch file
is found at doc/win/pygsl_windows_compile.bat or can be downloaded
here. Change it to your
needs and start it from the command shell.
@echo off
rem Batch processing file for building pygsl with mingw64 from msys2
rem The path to your python installation
set MYPYTHONDIR=C:\LocalPrograms\Python361\
rem set MYPYTHONDIR=C:\LocalPrograms\Python36-modified2\
rem set MYPYTHONDIR=C:\LocalPrograms\Anaconda3\
set PYTHONEXE=%MYPYTHONDIR%\python.exe
rem The path to your msys2 installation
set MSYS2PATH=C:\LocalPrograms\Msys2
set GSL_DIST_CONFIG=gsl_dist\gsl_site.py
if exist %GSL_DIST_CONFIG% (
echo Is your %GSL_DIST_CONFIG% up to date?
) else (
echo copy gsl_dist/gsl_site_example.py to %GSL_DIST_CONFIG%
echo and edit it so that it reflects your gsl installation!
exit /B
)
rem gcc shall be in the search path
set PATH=%PATH%;%MSYS2PATH%\mingw64\bin;
set LIBRARY_PATH=%MYPYTHONDIR%;
rem config now possible on windows :-)
rem lets see what your GSL installation provides
%PYTHONEXE% setup.py config --compiler=mingw32
rem %PYTHONEXE% setup.py gsl_wrappers
rem build the code
%PYTHONEXE% setup.py build --compiler=mingw32
rem and make the installer
%PYTHONEXE% setup.py build --compiler=mingw32 bdist --formats=msi
Uninstall GSL interface¶
rm -r “python install path”/lib/"pyhon version"/site-packages/pygsl
Testing¶
The directory tests contains several testsuites, based on python unittest. The script
run_test.py in this directory will run one test suit after the
other. Alternatively you can run
python setup.py nosetests
Support¶
Please send mails to our mailinglist at pygsl-discuss
Development¶
At last the development tree was migrated to git. You can browse our git tree at https://sourceforge.net/p/pygsl/GitRepro/ci/master/tree/
Type this to check out the repository:
git clone https://git.code.sf.net/p/pygsl/GitRepro pygsl-GitRepro
Some wrappers use swig http://swig.org ; thus a runnable recent swig is a perequisite. The wrapper code which is distributed together with the source is built using swig-3.
PyGSL provides tools for generating the wrapper code from source files. These tools can be executed by
python setup.py gsl_wrappers
Currently the wrapper code is generated for special functions. These are wrapped as numpy universal functions.
ToDo¶
complete implementation of modules
documentation
examples
test suits
History¶
a gsl-interface for python was needed for a project at
Center for Applied Informatics Cologne http://www.zaik.uni-koeln.de/AFS
gsl-0.0.3 was released at May 23, 2001
gsl-0.0.4 was released at January 8, 2002
gsl-0.0.5 was growing since January, 2002
gsl-0.2.0 was released at
gsl-0.3.0 was released at
gsl-0.3.1 was released at
gsl-0.3.2 was released at
gsl-0.9.4 was released at 25. October 2008
Thanks¶
Jochen Küpper for
pygsl.statisticsFabian Jakobs for
pygsl.blas,pygsl.eigen,pygsl.linalgandpygsl.permutationLeonardo Milano for rpm build
Eric Gurrola and Peter Stoltz for testing and supporting the port of pygsl to the MAC
Sebastien Maret for supporting the Fink http://fink.sourceforge.net port of pygsl.
and all for support by providing feed back on testing or showing by email that the code is useful for them
Information for Distributors¶
The information given here is intended for people distributing pygsl as well as for people who are not afraid to run code generation tools in case pygsl generates trouble.
Preferable array module¶
The only array module supported is numpy.
Wrapper generated modules¶
The following modules are generated by the SWIG wrappers:
_block
_callback
gslwrap
hankel
_poly
In case on of these modules shows a compilation error, just delete the
corresponding file in the swig_src directory (e.g.
swig_src/poly_wrap.c if for the poly module.). Set the variable
USE_SWIG to 1 in the setup.py file. Run the build process
again. Now setup.py should call swig and rebuild the module wrappers.
Dedicated wrappers¶
Some modules come with their own wrapping tools which are implemented in python.
The const module¶
Change into the src directory. Define the shell variable
PYGSL_GSLCVS variable, so that it either points to the GSL CVS
repository or to the include directory of your GSL installation
(typically /usr/include on a linux installation). Then type
python ../tools/constants_tool.py This will generate the files
const_m_array.c, const_num_array.c, const_cgsm_array.c
and const_mksa_array.c.
The special function module¶
PyGSL comes with one implementations for the special functions, which is currently found intesting.sf module.
Generating the wrapper has not been automatized yet. First swig is used to parse the header files and dump them into xml and then a specialized wrapper reads this tree and writes the wrappers.
First generate the wrapper by executing in the shell
python setup.py gsl_wrappers
Then run the build process. Set BUILD_TESTING = 1 in the setup.py
file. If required update the time stamp of the file
testing/src/sf/sfmodule_testing.c. This will build the module
_ufuncs.
The functions not wrapped automatically are defined in the file
sf.i
References¶
- 1
Note that it appears that this is the number of terms beyond the first term that are used. I.e. there are a total of \(\mathtt{terms\_used}+1\) terms:
\[\mathtt{sum\_plain} = \sum_{n=0}^{\mathtt{terms\_used}} a_{n}\]
Design of the PyGSL interface¶
The GSL library was implemented using the C language. This implies that each function uses a certain type for the different variables and are fixed to one specific type. The wrapper will try to convert each argument to the approbriate C type. The PyGSL interface tries to follow it as much as possible but only as far as resonable. For example the definition of the :c:function:`gsl_poly_eval function in C is given by
- double gsl\_poly\_eval(const double C[], const int LEN, const double X)
The corresponding python wrapper was implemented by
- poly.poly\_eval(C, x)
as the wrapper can get the length of any python object and then fill the len variable. The mathematical calculation is performed by the GSL library. Thus the calculation is limited to the precision provided by the underlying hardware.
Default arguments are used to allocate workspaces on the fly if not provided by the user. Consider for example the fft module. The function for the real forward transform is named
- int gsl\_fft\_real\_transform (double DATA[], size_t STRIDE, size_t N,
- const gsl_fft_real_wavetable * WAVETABLE, gsl_fft_real_workspace * WORK)
The corresponding python wrapper is provided by the function
- real\_transform(data, [space, table, output])
in the pygsl.fft
The wrapper will get the stride and size information from the data object provided by the user. If space or table are not provided, these objects will be generated on the fly. As the GSL function applies the transformation in space, an internal copy is made of the data and only then the object is passed to the GSL function. If an output object is provided the data will be copied there instead. PyGSL will always make copies of objects which would be otherwise modified in place.
Callbacks¶
Solvers require as one argument a user function to work on which have to be provided by the user. These callbacks typically are of the form
Please note that this function must return the exact number of arguments as given in the example. The wrappers around callbacks go a long way to try to provide meaningfull error messages. If a solver fails, please check that the number of input and output arguments it takes are correct.
Error handling¶
As GSL is a C library error handling is implemented using an error
handler and return values. PyGSL generates python exceptions out of
these values. See pygsl.errors for a list of the
exceptions.
The GSL error numbers are given in pygsl.errno.
Exception handling¶
GSL provides a selectable error handler, that is called for occuring errors (like domain errors, division by zero, etc. ). This is switched off. Instead each wrapper function will check the error return value and in case of error an python exception is created.
Here is a python level example:
import pygsl.histogram
import pygsl.errors
hist=pygsl.histogram.histogram2d(100,100)
try:
hist[-1,-1]=0
except pygsl.errors.gsl_Error as err:
print err
Will result in
input domain error: index i lies outside valid range of 0 .. nx - 1
An exception are ufuncs in the testings.sf module (see section[sec:ufuncs]).
Change of internal error handling.¶
Before a error handler was installed by init_pygsl into gsl which translated the error code (and the message) to a python exception. This required that the GIL was available, which numpy ufuncs dispose. Thus now this gsl error handler is deactivated and instead the C error code returned by the C function is translated to an error code by the wrapper called from python.
UFuncs do not call this handler now at all.
The documentation gap¶
PyGSL does still lack an appropriate documentation. Most documentation is accessible over the internal documentation strings. These are accessible as attributes (the help function does not always show them). It can be sometimes necessary to create an object to see its methods as well as the documentation of the methods (e.g.a random number generator in the rng module to see its methods). The directory contains examples for (nearly each) module.
Please feel welcome to add to the documentation!
Acknowledgment¶
Parts of this this manual are based on the GNU Scientific Library reference manual.
The authors want to thank all for contribution of code, support material for generating distribution packages, bug reports and example scripts.
PyGSL application programming interface¶
pygsl module¶
Subpackages¶
Submodules¶
pygsl.errno module¶
pygsl.errors module¶
pygsl.math module¶
pygsl.testing.complex module¶
pygsl.poly module¶
Special Functions¶
Airy Functions¶
Bessel Functions¶
Clausen Functions¶
Coulomb Functions¶
Coupling Functions¶
Dawson Function¶
Debye Functions¶
Dilogarithm¶
Elementary Operations¶
Ellipitcal Integrals¶
Error Functions¶
Exponential Functions and Integrals¶
Fermi Dirac Functions¶
Gamma and Beta Functions¶
Gegenbauer Functions¶
Hermite Polynomials and Functions¶
Hypergeometric Functions¶
Laguerre Functions¶
Lambert Functions¶
Legendre Functions and Spherical Harmonics¶
Mathieu functions¶
Power functions¶
Psi functions¶
Synchrotron functions¶
Transport Functions¶
Trigonometric Functions¶
Zeta Functions¶
Complex implementations of standard functions¶
Unsorted functions¶
Hydrogenic functions¶
pygsl.permutation module¶
pygsl.combination module¶
pygsl.blas module¶
pygsl.linalg module¶
pygsl.eigen module¶
pygsl.fft module¶
pygsl.integrate module¶
pygsl.rng module¶
pygsl.qrng module¶
pygsl.statistics module¶
pygsl.monte module¶
pygsl.siman module¶
pygsl.odeiv2 module¶
pygsl.interpolation module¶
pygsl.spline module¶
pygsl.interpolation2d module¶
pygsl.deriv module¶
pygsl.chebyshev module¶
pygsl.sum module¶
pygsl.wavelet module¶
pygsl.hankel module¶
pygsl.roots module¶
pygsl.minimize module¶
pygsl.multiroots module¶
pygsl.multiminimize module¶
pygsl.fit module¶
pygsl.multifit module¶
pygsl.multifit_nlin module¶
pygsl.multifit_robust module¶
pygsl.bspline module¶
pygsl.ieee module¶
Modules not considered part of the API¶
Modules for testing internals¶
GNU Free Documentation License¶
Preamble¶
The purpose of this License is to make a manual, textbook, or other written document “free” in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
Applicability and Definitions¶
This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
Verbatim Copying¶
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
Copying in Quantity¶
If you publish printed copies of the Document numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
Modifications¶
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
State on the Title page the name of the publisher of the Modified Version, as the publisher.
Preserve all the copyright notices of the Document.
Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
Include an unaltered copy of this License.
Preserve the section entitled “History”, and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
In any section entitled “Acknowledgements” or “Dedications”, preserve the section’s title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
Delete any section entitled “Endorsements”. Such a section may not be included in the Modified Version.
Do not retitle any existing section as “Endorsements” or to conflict in title with any Invariant Section.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.
You may add a section entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties – for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
Combining Documents¶
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections entitled “History” in the various original documents, forming one section entitled “History”; likewise combine any sections entitled “Acknowledgements”, and any sections entitled “Dedications”. You must delete all sections entitled “Endorsements.”
Collections of Documents¶
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
Aggregation With Independent Works¶
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an “aggregate”, and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document’s Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.
Translation¶
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.
Termination¶
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
Future Revisions of This License¶
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.