\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}

@ifinfo
This 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 of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by 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 1filll
Copyright @copyright{} 1996,1997,1998,1999,2000,2001 The GSL Project.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end titlepage

@contents

@node Top, Motivation, (dir), (dir)
@top About GSL

@ifinfo
This file documents the design of @value{GSL}, a collection of numerical
routines for scientific computing.

More information about GSL can be found at the project homepage,
@url{http://www.gnu.org/software/gsl/}.
@end ifinfo

The @value{GSL} is a library of scientific subroutines.  It aims to
provide a convenient interface to routines that do standard (and not so
standard) tasks that arise in scientific research.  More than that, it
also provides the source code.  Users are welcome to alter, adjust,
modify, and improve the interfaces and/or implementations of whichever
routines might be needed for a particular purpose.

GSL is intended to provide a free equivalent to existing proprietary
numerical 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 to
provide something which is generally useful, and the library is aimed at
general users rather than specialists.

@menu
* Motivation::                  
* Design::                      
* Copying::                     
@end menu

@node Motivation, Design, Top, Top
@chapter Motivation
@cindex numerical analysis
@cindex free software

There is a need for scientists and engineers to have a numerical library
that:
@itemize @bullet
@item
is free (in the sense of freedom, not in the sense of gratis; see the
GNU General Public License), so that people can use that library,
redistribute it, modify it @dots{}
@item
is written in C using modern coding conventions, calling conventions,
scoping @dots{}
@item
is clearly and pedagogically documented; preferably with TeXinfo, so as
to allow online info, WWW and TeX output.
@item
uses top quality state-of-the-art algorithms.
@item
is portable and configurable using @emph{autoconf} and @emph{automake}.
@item
basically, is GNUlitically correct.
@end itemize

There are strengths and weaknesses with existing libraries:

@emph{Netlib} (http://www.netlib.org/) is probably the most advanced set
of numerical algorithms available on the net, maintained by AT&T.
Unfortunately most of the software is written in Fortran, with strange
calling 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 set
of pointers to scientific software, but like netlib, the individual
routines 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 the
algorithms in a very clear way.  Unfortunately the authors released the
source code under a license which allows you to use it, but prevents you
from re-distributing it.  Thus Numerical Recipes is not @emph{free} in
the sense of @emph{freedom}.  On top of that, the implementation suffers
from @emph{fortranitis} and other
limitations. [http://www.lysator.liu.se/c/num-recipes-in-c.html]

@emph{SLATEC} is a large public domain collection of numerical routines
in Fortran written under a Department of Energy program in the
1970's. The routines are well tested and have a reasonable overall
design (given the limitations of that era).  GSL should aim to be a
modern version of SLATEC.

@emph{NSWC} is the Naval Surface Warfare Center numerical library.  It
is a large public-domain Fortran library, containing a lot of
high-quality code.  Documentation for the library is hard to find, only
a few photocopies of the printed manual are still in circulation.

@emph{NAG} and @emph{IMSL} both sell high-quality libraries which are
proprietary.  The NAG library is more advanced and has wider scope than
IMSL. The IMSL library leans more towards ease-of-use and makes
extensive use of variable length argument lists to emulate "default
arguments".

@emph{ESSL} and @emph{SCSL} are proprietary libraries from IBM and SGI.

Forth Scientific Library [see the URL
http://www.taygeta.com/fsl/sciforth.html].  Mainly of interest to Forth
users.

@emph{Numerical Algorithms with C} G. Engeln-Mullges, F. Uhlig. A nice
numerical library written in ANSI C with an accompanying
textbook. Source code is available but the library is not free software.

@emph{NUMAL} A C version of the NUMAL library has been written by
H.T. Lau and is published as a book and disk with the title "A Numerical
Library in C for Scientists and Engineers". Source code is available but
the library is not free software.

@emph{C Mathematical Function Handbook} by Louis Baker. A library of
function approximations and methods corresponding to those in the
"Handbook of Mathematical Functions" by Abramowitz and Stegun.  Source
code is available but the library is not free software.

@emph{CCMATH} by Daniel A. Atkinson. A C numerical library covering
similar areas to GSL. The code is quite terse.  Earlier versions were
under the GPL but unfortunately it has changed to the LGPL in recent
versions.

@emph{CEPHES} A useful collection of high-quality special functions
written in C. Not GPL'ed.

@emph{WNLIB} A small collection of numerical routines written in C by
Will Naylor. Public domain.

@emph{MESHACH} A comprehensive matrix-vector linear algebra library
written in C. Freely available but not GPL'ed (non-commercial license).

@emph{CERNLIB} is a large high-quality Fortran library developed at CERN
over many years.  It was originally non-free software but has recently
been released under the GPL.

@emph{COLT} is a free numerical library in Java developed at CERN by
Wolfgang Hoschek.  It is under a BSD-style license.

The long-term goal will be to provide a framework to which the real
numerical 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 languages

Wrapper 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 implemented

Anything which is in any of the existing libraries.  Obviously it makes
sense 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.