


GNU Scientific Library for Lisp




===============================








[GSLL](index.html)








 [About](#about)




 [Examples](#examples)




 [Requirements](#require)




 [Download](#getit)




 [Documentation](#documentation)




 [Status](#status)




 [Contact](#contact)








About













The GNU Scientific Library for Lisp (GSLL) allows you to use the [GNU Scientific Library (GSL)](http://www.gnu.org/software/gsl/) from [Common Lisp](http://www.lisp.org). This library provides a full range of common mathematical operations useful to scientific and engineering applications. The design of the GSLL interface is such that access to most of the GSL library is possible in a Lispnatural way; the intent is that the user not be hampered by the restrictions of the C language in which GSL has been written. GSLL thus provides interactive use of GSL for getting quick answers, even for someone not intending to program in Lisp.








Topics include: polynomials, special functions, vectors and matrices, permutations, sorting, linear algebra including BLAS, eigensystems, fast Fourier transforms (FFT), quadrature, random numbers, quasirandom sequences, random distributions, statistics, histograms, Ntuples, Monte Carlo integration, simulated annealing, ordinary differential equations, interpolation, numerical integration, numerical differentiation, Chebyshev approximation, series acceleration, discrete Hankel transforms, rootfinding, minimization, leastsquares fitting, IEEE floatingpoint, discrete wavelet transforms, basis splines, physical constants. See [missingfeatures.text](missingfeatures.text) on the status of some incomplete topics.








Examples













The [Jacobian elliptic functions](http://www.gnu.org/software/gsl/manual/html_node/EllipticFunctions_0028Jacobi_0029.html) *sn*, *cn*, and *dn* are special functions (Chapter 7):








(jacobianellipticfunctions 0.2d0 0.81d0)




0.19762082367187703d0




0.9802785369736752d0




0.9840560289645665d0








which returns as multiple values the three function values. The functions are defined only if the second argument *m* is not greater than 1, so an error is signalled if this parameter is out of range:








(jacobianellipticfunctions 0.61802d0 1.5d0)




Input domain error m > 1.0 in elljac.c at line 46




[Condition of type INPUTDOMAIN]








This is an ordinary Lisp error which may be handled with standard definitions available in Lisp. To take the [complex conjugate scalar product](file:///usr/share/doc/gslrefhtml/Level1GSLBLASInterface.html) of two complex vectors of length 3:








(cdot #2m(#c(34.5d0 8.24d0) #c(3.29d0 8.93d0) #c(34.12d0 6.15d0))




#2m(#c(49.27d0 13.49d0) #c(32.5d0 42.73d0) #c(17.24d0 43.31d0)))




#C(2940.2118d0 1861.9380999999998d0)








There are over 1500 examples available from within GSLL with the function `examples`. There is also a suite of over 4000 tests; many of the examples also serve as tests, and most others are ported from GSL's tests.








Download and Install













### Download








Use [quicklisp](http://www.quicklisp.org/) and follow the instructions. You will need to make sure that the libraries and header files associated with [GNU Scientific Library (GSL)](http://www.gnu.org/software/gsl/) and [libffi](http://sourceware.org/libffi/) are installed; your distribution may name these `libgsl0dev` and `libffidev`. Once they are installed and you have loaded the quicklisp file:








(ql:quickload "gsll")








To test your installation:








(asdf:testsystem :gsll)








The result should look something like:








Unit Test Summary




 3997 assertions total




 3992 passed




 5 failed




 6 execution errors




 0 missing tests








You may see more failures; if you are not on a 64 bit platform you will see fewer assertions.








### License








This software is distributed under the [GPL](http://www.gnu.org/licenses/gpl.html) ; see the file COPYING. There is absolutely no warranty.








Documentation













### General Advice








The following techniques for using the API are advised:








 Find the appropriate function(s) in the [GSL documentation](http://www.gnu.org/software/gsl/manual/).




 Use the GSLL function `gsllookup` to find the equivalent GSLL function, for example








(gsllookup "gsl_sf_elljac_e")




JACOBIANELLIPTICFUNCTIONS




T








to find that the Lisp function name is `#'jacobianellipticfunctions`.








 Look at the documentation for that Lisp function, e.g.








(documentation #'jacobianellipticfunctions 'function)




"The Jacobian elliptic functions sn(um),




cn(um), dn(um) computed by descending Landen transformations."












to get an explanation of the arguments etc.








 Use the function `(examples)` without an argument to get a list of example categories. Then use the function with a category name as the argument to get a list of examples under that category, for example `(examples 'highermoments)`. The result will be a list of forms, each providing an example of usage in the relevant topic. If the [GSL documentation](http://www.gnu.org/software/gsl/manual/) provides an example, there will usually be the same or similar example provided in GSLL. *Note:* Some of the examples are intentionally designed to signal an error, because the examples also serve as a regression (unit) test suite for GSLL.








Some examples are not yet present in, or are too complicated for, the function `#'examples`. In this case, you need to look in the relevant source file; they are in either a separate file of examples, or at the end of the file of definitions. It is advisable to look at the examples first for calculations that require more complex setup (generally, the later chapters in the GSL manual).








### Arrays








GSLL has many functions that work on vectors (onedimensional arrays) and matrices (twodimensional arrays). Foreign arrays are defined and manipulated using the [Antik](http://www.commonlisp.net/project/antik/) which defines generic operations on arraylike objects; see the Antik documentation for more information. GSLL supports all array element types that are supported by CFFI, the CL implementation, GSL, and the platform. This list is available in the variable `grid:*arrayelementtypes*`.








### Passing functions








Functions that are passed to GSL functions (known as *callbacks* in C) are specified with a [function designator](http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_f.htm#function_designator) for the CL function, that is, either the function object itself or a symbol denoting the function. There is usually an option `scalarsp` for functions that take or return arrays that, if true, will send the user function the argument element by element, and expect the return values to be the individual elements.








### GSL objects








There are a number of GSL objects other than arrays that can be created:








acceleration interpolation levin levintruncated spline




nonlinearffit nonlinearfdffit




onedimensionalrootsolverf onedimensionalrootsolverfdf




multidimensionalminimizerf multidimensionalminimizerfdf




fitworkspace onedimensionalminimizer




multidimensionalrootsolverf multidimensionalrootsolverfdf




histogram histogram2d histogrampdf histogram2dpdf




basisspline chebyshev hankel wavelet waveletworkspace




randomnumbergenerator quasirandomnumbergenerator discreterandom




polynomialcomplexworkspace integrationworkspace




qawstable qawotable




eigensymm eigensymmv eigenherm eigenhermv




eigennonsymm eigennonsymmv eigengensymm eigengensymmv




eigengen eigengenv




montecarloplain montecarlomiser montecarlovegas




odestepper odeevolution standardcontrol ycontrol




ypcontrol scaledcontrol




fftrealwavetabledoublefloat fftrealwavetablesinglefloat




fftrealworkspacedoublefloat fftrealworkspacesinglefloat




fftcomplexwavetabledoublefloat fftcomplexwavetablesinglefloat




fftcomplexworkspacedoublefloat fftcomplexworkspacesinglefloat




ffthalfcomplexwavetabledoublefloat ffthalfcomplexwavetablesinglefloat








An instance may be created with a function whose name is "make" followed by the class name, e.g. `makehistogram`. The arguments that the function takes depends on the class.








### Additional definitions








Some definitions are provided because of their usefulness, even though GSL doesn't have them.








 `invertmatrix` finds the inverse of a matrix and uses GSL's LU decomposition functions.




 IEEE floating point number analysis.




 `fftfrequencyvector` returns a vector where the sample frequencies are contained. If you perform an FFT on a vector of a given size and :samplesize, this vector will contain the sample frequencies in order. If the :shifted keyword is T, then the frequencies are ordered in ascending order.




 `fftshift` returns a copy of a vector where the zero frequency has been shifted to the center; the frequency components will be sorted according to their frequency, in ascending order. Optionally, a :stride can be provided.




 `fftinverseshift` performs the inverse action of fftshift; the zero and positive frequency components are shifted to the beginning, so that the resulting vector is suitable for an inverse FFT. Optionally, a :stride can be provided.








Status













GSLL is largely complete and usable, with functioning interfaces to most of GSL. Some functionality is not yet ported; see [missingfeatures.text](missingfeatures.text) for more details. Known bugs are documented in [status.text](status.text). Work is ongoing to both remedy those deficiencies and to simplify the user interface by changing more required arguments into optional or key arguments with useful default values. Typically, these arguments bind GSL objects and arrays used internally or for function return.








Contact













There is a [mailing list](https://mailman.commonlisp.net/listinfo/gslldevel) for all aspects of this project, including bug reports. See also the [archives](https://mailman.commonlisp.net/pipermail/gslldevel/). In addition, I am frequently on \#lisp IRC channel as LiamH. For bug reports, please use the mailing list. The [development site](https://gitlab.commonlisp.net/antik/gsll) for GSLL has the git repository. If you have patch(es), please commit your changes and do:








git formatpatch origin








This will produce one or more files whose names start with a fourdigit number; please attach them all to your email.

















[Liam Healy](mailto:gslldevel@commonlisp.net)




Timestamp: 