\input texinfo @c -*-texinfo-*-@c %**start of header@setfilename gsl-design.info@settitle GNU Scientific Library@finalout@c -@setchapternewpage odd@c %**end of header@dircategory Scientific software@direntry* GSL-design: (GSL-design).             GNU Scientific Library -- Design@end direntry@comment @include version-design.texi@set GSL @i{GNU Scientific Library}@ifinfoThis file documents the @value{GSL}.Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001 The GSL Project.Permission is granted to make and distribute verbatim copies ofthis manual provided the copyright notice and this permission noticeare preserved on all copies.@ignorePermission is granted to process this file through TeX and print theresults, provided the printed document carries copying permissionnotice identical to this one except for the removal of this paragraph(this paragraph not being relevant to the printed manual).@end ignorePermission is granted to copy and distribute modified versions of thismanual under the conditions for verbatim copying, provided that the entireresulting derived work is distributed under the terms of a permissionnotice identical to this one.Permission is granted to copy and distribute translations of this manualinto another language, under the above conditions for modified versions,except that this permission notice may be stated in a translation approvedby the Foundation.@end ifinfo@titlepage@title GNU Scientific Library -- Design document@comment @subtitle Edition @value{EDITION}, for gsl Version @value{VERSION}@comment @subtitle @value{UPDATED}@author Mark Galassi Los Alamos National Laboratory@author James Theiler Astrophysics and Radiation Measurements Group, Los Alamos National Laboratory@author Brian Gough Network Theory Limited@page@vskip 0pt plus 1filllCopyright @copyright{} 1996,1997,1998,1999,2000,2001 The GSL Project.Permission is granted to make and distribute verbatim copies ofthis manual provided the copyright notice and this permission noticeare preserved on all copies.Permission is granted to copy and distribute modified versions of thismanual under the conditions for verbatim copying, provided that the entireresulting derived work is distributed under the terms of a permissionnotice identical to this one.Permission is granted to copy and distribute translations of this manualinto another language, under the above conditions for modified versions,except that this permission notice may be stated in a translation approvedby the Foundation.@end titlepage@contents@node Top, Motivation, (dir), (dir)@top About GSL@ifinfoThis file documents the design of @value{GSL}, a collection of numericalroutines for scientific computing.More information about GSL can be found at the project homepage,@url{http://www.gnu.org/software/gsl/}.@end ifinfoThe @value{GSL} is a library of scientific subroutines.  It aims toprovide a convenient interface to routines that do standard (and not sostandard) tasks that arise in scientific research.  More than that, italso provides the source code.  Users are welcome to alter, adjust,modify, and improve the interfaces and/or implementations of whicheverroutines might be needed for a particular purpose.GSL is intended to provide a free equivalent to existing proprietarynumerical libraries written in C or Fortran, such as NAG, IMSL's CNL,IBM's ESSL, and SGI's SCSL.The target platform is a low-end desktop workstation. The goal is toprovide something which is generally useful, and the library is aimed atgeneral users rather than specialists.@menu* Motivation::                  * Design::                      * Copying::                     @end menu@node Motivation, Design, Top, Top@chapter Motivation@cindex numerical analysis@cindex free softwareThere is a need for scientists and engineers to have a numerical librarythat:@itemize @bullet@itemis free (in the sense of freedom, not in the sense of gratis; see theGNU General Public License), so that people can use that library,redistribute it, modify it @dots{}@itemis written in C using modern coding conventions, calling conventions,scoping @dots{}@itemis clearly and pedagogically documented; preferably with TeXinfo, so asto allow online info, WWW and TeX output.@itemuses top quality state-of-the-art algorithms.@itemis portable and configurable using @emph{autoconf} and @emph{automake}.@itembasically, is GNUlitically correct.@end itemizeThere are strengths and weaknesses with existing libraries:@emph{Netlib} (http://www.netlib.org/) is probably the most advanced setof numerical algorithms available on the net, maintained by AT&T.Unfortunately most of the software is written in Fortran, with strangecalling conventions in many places.  It is also not very well collected,so it is a lot of work to get started with netlib.@emph{GAMS} (http://gams.nist.gov/) is an extremely well organized setof pointers to scientific software, but like netlib, the individualroutines vary in their quality and their level of documentation.@emph{Numerical Recipes} (http://www.nr.com,http://cfata2.harvard.edu/nr/) is an excellent book: it explains thealgorithms in a very clear way.  Unfortunately the authors released thesource code under a license which allows you to use it, but prevents youfrom re-distributing it.  Thus Numerical Recipes is not @emph{free} inthe sense of @emph{freedom}.  On top of that, the implementation suffersfrom @emph{fortranitis} and otherlimitations. [http://www.lysator.liu.se/c/num-recipes-in-c.html]@emph{SLATEC} is a large public domain collection of numerical routinesin Fortran written under a Department of Energy program in the1970's. The routines are well tested and have a reasonable overalldesign (given the limitations of that era).  GSL should aim to be amodern version of SLATEC.@emph{NSWC} is the Naval Surface Warfare Center numerical library.  Itis a large public-domain Fortran library, containing a lot ofhigh-quality code.  Documentation for the library is hard to find, onlya few photocopies of the printed manual are still in circulation.@emph{NAG} and @emph{IMSL} both sell high-quality libraries which areproprietary.  The NAG library is more advanced and has wider scope thanIMSL. The IMSL library leans more towards ease-of-use and makesextensive use of variable length argument lists to emulate "defaultarguments".@emph{ESSL} and @emph{SCSL} are proprietary libraries from IBM and SGI.Forth Scientific Library [see the URLhttp://www.taygeta.com/fsl/sciforth.html].  Mainly of interest to Forthusers.@emph{Numerical Algorithms with C} G. Engeln-Mullges, F. Uhlig. A nicenumerical library written in ANSI C with an accompanyingtextbook. Source code is available but the library is not free software.@emph{NUMAL} A C version of the NUMAL library has been written byH.T. Lau and is published as a book and disk with the title "A NumericalLibrary in C for Scientists and Engineers". Source code is available butthe library is not free software.@emph{C Mathematical Function Handbook} by Louis Baker. A library offunction approximations and methods corresponding to those in the"Handbook of Mathematical Functions" by Abramowitz and Stegun.  Sourcecode is available but the library is not free software.@emph{CCMATH} by Daniel A. Atkinson. A C numerical library coveringsimilar areas to GSL. The code is quite terse.  Earlier versions wereunder the GPL but unfortunately it has changed to the LGPL in recentversions.@emph{CEPHES} A useful collection of high-quality special functionswritten in C. Not GPL'ed.@emph{WNLIB} A small collection of numerical routines written in C byWill Naylor. Public domain.@emph{MESHACH} A comprehensive matrix-vector linear algebra librarywritten in C. Freely available but not GPL'ed (non-commercial license).@emph{CERNLIB} is a large high-quality Fortran library developed at CERNover many years.  It was originally non-free software but has recentlybeen released under the GPL.@emph{COLT} is a free numerical library in Java developed at CERN byWolfgang Hoschek.  It is under a BSD-style license.The long-term goal will be to provide a framework to which the realnumerical experts (or their graduate students) will contribute. @node Design, Copying, Motivation, Top@chapter Design@menu* Language for implementation::  * Interface to other languages::  * What routines are implemented::  * What routines are not implemented::  * Design of  Numerical Libraries::  * Code Reuse::                  * Standards and conventions::   * Background and Preparation::  * Documentation::               * Namespace::                   * Header files::                * Target system::               * Function Names::              * Object-orientation::          * Comments::                    * Minimal structs::             * Algorithm decomposition::     * Memory allocation and ownership::  * Memory layout::               * Linear Algebra Levels::       * Exceptions and Error handling::  * Persistence::                 * Using Return Values::         * Variable Names::              * Datatype widths::             * size_t::                      * Arrays vs Pointers::          * Pointers::                    * Constness::                   * Pseudo-templates::            * Arbitrary Constants::         * Test suites::                 * Compilation::                 * Thread-safety::               * Legal issues::                * Non-UNIX portability::        * Compatibility with other libraries::  * Parallelism::                 * Precision::                   * Miscellaneous::               @end menu@node Language for implementation, Interface to other languages, Design, Design@section Language for implementation@strong{One language only (C)}Advantages: simpler, compiler available and quite universal.@node Interface to other languages, What routines are implemented, Language for implementation, Design@section Interface to other languagesWrapper packages are supplied as "extra" packages; not as part of the"core". They are maintained separately by independent contributors.Use standard tools to make wrappers: swig, g-wrap@node What routines are implemented, What routines are not implemented, Interface to other languages, Design@section What routines are implementedAnything which is in any of the existing libraries.  Obviously it makessense to prioritize and write code for the most important areas first.@c @itemize @bullet@c @item Random number generators@c Includes both random number generators and routines to give various@c interesting distributions.@c @item Statistics@c @item Special Functions@c What I (jt) envision for this section is a collection of routines for@c reliable and accurate (but not necessarily fast or efficient) estimation@c of values for special functions, explicitly using Taylor series, asymptotic @c expansions, continued fraction expansions, etc.  As well as these routines,@c fast approximations will also be provided, primarily based on Chebyschev@c polynomials and ratios of polynomials.  In this vision, the approximations@c will be the "standard" routines for the users, and the exact (so-called)@c routines will be used for verification of the approximations.  It may also@c be useful to provide various identity-checking routines as part of the@c verification suite.@c @item Curve fitting@c polynomial, special functions, spline@c @item Ordinary differential equations@c @item Partial differential equations@c @item Fourier Analysis@c @item Wavelets@c @item Matrix operations: linear equations@c @item Matrix operations: eigenvalues and spectral analysis@c @item Matrix operations: any others?@c @item Direct integration@c @item Monte carlo methods@c @item Simulated annealing@c @item Genetic algorithms@c We need to think about what kinds of algorithms are basic generally@c useful numerical algorithms, and which ones are special purpose@c research projects.  We should concentrate on supplying the former.