gsl-design.texi

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY without ev

\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, 2004 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,2004 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,
@uref{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::                  
* Contributing::                
* Design::                      
* Copying::                     
@end menu

@node Motivation, Contributing, 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.

@emph{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  Contributing, Design, Motivation, Top
@chapter Contributing

This design document was originally written in 1996.  As of 2004, GSL
itself is essentially feature complete, the developers are not actively
working on any major new functionality.

The main emphasis is now on ensuring the stability of the existing
functions, improving consistency, tidying up a few problem areas and
fixing any bugs that are reported.  Potential contributors are
encouraged to gain familiarity with the library by investigating and
fixing known problems listed in the @file{BUGS} file in the CVS
repository.

Adding large amounts of new code is difficult because it leads to
differences in the maturity of different parts of the library.  To
maintain stability, any new functionality is encouraged as
@dfn{packages}, built on top of GSL and maintained independently by the
author, as in other free software projects (such as the Perl CPAN
archive and TeX CTAN archive, etc).

@menu
* Packages::                    
@end menu

@node Packages,  , Contributing, Contributing
@section Packages

The design of GSL permits extensions to be used alongside the existing
library easily by simple linking.  For example, additional random number
generators can be provided in a separate library:

@example
$ tar xvfz rngextra-0.1.tar.gz
$ cd rngextra-0.1
$ ./configure; make; make check; make install
$ ...
$ gcc -Wall main.c -lrngextra -lgsl -lgslcblas -lm
@end example

The points below summarise the package design guidelines.  These are
intended to ensure that packages are consistent with GSL itself, to make
life easier for the end-user and make it possible to distribute popular
well-tested packages as part of the core GSL in future.

@itemize @bullet
@item Follow the GSL and GNU coding standards described in this document

This means using the standard GNU packaging tools, such as Automake,
providing documentation in Texinfo format, and a test suite.  The test
suite should run using @samp{make check}, and use the test functions
provided in GSL to produce the output with @code{PASS:}/@code{FAIL:}
lines.  It is not essential to use libtool since packages are likely to
be small, a static library is sufficient and simpler to build.

@item Use a new unique prefix for the package (do not use @samp{gsl_} -- this is reserved for internal use).

For example, a package of additional random number generators might use
the prefix @code{rngextra}.

@example
#include <rngextra.h>

gsl_rng * r = gsl_rng_alloc (rngextra_lsfr32);
@end example

@item Use a meaningful version number which reflects the state of development

Generally, @code{0.x} are alpha versions, which provide no guarantees.
Following that, @code{0.9.x} are beta versions, which should be essentially
complete, subject only to minor changes and bug fixes.  The first major
release is @code{1.0}.  Any version number of @code{1.0} or higher
should be suitable for production use with a well-defined API.

The API must not change in a major release and should be
backwards-compatible in its behavior (excluding actual bug-fixes), so
that existing code do not have to be modified.  Note that the API
includes all exported definitions, including data-structures defined
with @code{struct}.  If you need to change the API in a package, it
requires a new major release (e.g. @code{2.0}).

@item Use the GNU General Public License (GPL)

Follow the normal procedures of obtaining a copyright disclaimer if you
would like to have the package considered for inclusion in GSL itself in
the future (@pxref{Legal issues}).
@end itemize

Post announcements of your package releases to
@email{gsl-discuss@@sources.redhat.com} so that information about them
can be added to the GSL webpages.

For security, sign your package with GPG (@code{gpg --detach-sign
@var{file}}).

An example package @samp{rngextra} containing two additional random
number generators can be found at
@url{http://www.network-theory.co.uk/download/rngextra/}.

@node Design, Copying, Contributing, 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::  
* Choice of Algorithms::        
* Documentation::               
* Namespace::                   
* Header files::                
* Target system::               
* Function Names::              
* Object-orientation::          
* Comments::                    
* Minimal structs::             
* Algorithm decomposition::     
* Memory allocation and ownership::  
* Memory layout::               
* Linear Algebra Levels::       
* Error estimates::             
* 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.