\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 copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.2 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 the section entitled ``GNU Free

Documentation License''.

@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::                      

* Bibliography::                

* Copying::                     

* GNU Free Documentation License::  

@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@@sourceware.org} 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, Bibliography, 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.

@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 Chebyshev

@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.

@c @item Cellular automata

@c @end itemize

@node What routines are not implemented, Design of  Numerical Libraries, What routines are implemented, Design

@section What routines are not implemented

@itemize @bullet

@item anything which already exists as a high-quality GPL'ed package.

@item anything which is too big

 -- i.e. an application in its own right rather than a subroutine

For example, partial differential equation solvers are often huge and

very specialized applications (since there are so many types of PDEs,

types of solution, types of grid, etc).  This sort of thing should

remain separate.  It is better to point people to the good applications

which exist.

@item anything which is independent and useful separately.

Arguably functions for manipulating date and time, or financial

functions might be included in a "scientific" library.  However, these

sorts of modules could equally well be used independently in other

programs, so it makes sense for them to be separate libraries.

@end itemize

@node  Design of  Numerical Libraries, Code Reuse, What routines are not implemented, Design

@section  Design of  Numerical Libraries

In writing a numerical library there is a unavoidable conflict between

completeness and simplicity.  Completeness refers to the ability to

perform operations on different objects so that the group is

"closed". In mathematics objects can be combined and operated on in an

infinite number of ways.  For example, I can take the derivative of a

scalar field with respect to a vector and the derivative of a vector

field wrt.@: a scalar (along a path).

There is a definite tendency to unconsciously try to reproduce all these

possibilities in a numerical library, by adding new features one by

one. After all, it is always easy enough to support just one more

feature @dots{} so why not?

Looking at the big picture, no-one would start out by saying "I want to

be able to represent every possible mathematical object and operation

using C structs" -- this is a strategy which is doomed to fail.  There

is a limited amount of complexity which can be represented in a

programming language like C.  Attempts to reproduce the complexity of

mathematics within such a language would just lead to a morass of

unmaintainable code.  However, it's easy to go down that road if you

don't think about it ahead of time.

It is better to choose simplicity over completeness.  In designing new

parts of the library keep modules independent where possible. If

interdependencies between modules are introduced be sure about where you

are going to draw the line.

@node Code Reuse, Standards and conventions, Design of  Numerical Libraries, Design

@section Code Reuse

It is useful if people can grab a single source file and include it in

their own programs without needing the whole library.  Try to allow

standalone files like this whenever it is reasonable.  Obviously the

user might need to define a few macros, such as GSL_ERROR, to compile

the file but that is ok.  Examples where this can be done: grabbing a

single random number generator.

@node Standards and conventions, Background and Preparation, Code Reuse, Design

@section Standards and conventions

The people who kick off this project should set the coding standards and

conventions.  In order of precedence the  standards that we follow are,

@itemize @bullet

@item We follow the GNU Coding Standards.

@item We follow the conventions of the ANSI Standard C Library.

@item We follow the conventions of the GNU C Library.

@item We follow the conventions of the glib GTK support Library.

@end itemize

The references for these standards are the @cite{GNU Coding Standards}

document, Harbison and Steele @cite{C: A Reference Manual}, the

@cite{GNU C Library Manual} (version 2), and the Glib source code.

For mathematical formulas, always follow the conventions in Abramowitz &

Stegun, the @cite{Handbook of Mathematical Functions}, since it is the

definitive reference and also in the public domain.

If the project has a philosophy it is to "Think in C".  Since we are

working in C we should only do what is natural in C, rather than trying

to simulate features of other languages.  If there is something which is

unnatural in C and has to be simulated then we avoid using it. If this

means leaving something out of the library, or only offering a limited

version then so be it.  It is not worthwhile making the library

over-complicated.  There are numerical libraries in other languages, and

if people need the features of those languages it would be sensible for

them to use the corresponding libraries, rather than coercing a C

library into doing that job.  

It should be borne in mind at all time that C is a macro-assembler.  If

you are in doubt about something being too complicated ask yourself the

question "Would I try to write this in macro-assembler?" If the answer

is obviously "No" then do not try to include it in GSL. [BJG]

It will be useful to read the following papers,

@itemize @w{}

@item 

Kiem-Phong Vo, ``The Discipline and Method Architecture for Reusable

Libraries'', Software - Practice & Experience, v.30, pp.107-128, 2000.

@end itemize

@noindent

It is available from

@uref{http://www.research.att.com/sw/tools/sfio/dm-spe.ps} or the earlier

technical report Kiem-Phong Vo, "An Architecture for Reusable Libraries"

@uref{http://citeseer.nj.nec.com/48973.html}.

There are associated papers on Vmalloc, SFIO, and CDT which are also

relevant to the design of portable C libraries.

@itemize @w{}

@item

Kiem-Phong Vo, ``Vmalloc: A General and Efficient Memory

Allocator''. Software Practice & Experience, 26:1--18, 1996.

@uref{http://www.research.att.com/sw/tools/vmalloc/vmalloc.ps}

@item

Kiem-Phong Vo. ``Cdt: A Container Data Type Library''. Soft. Prac. &

Exp., 27:1177--1197, 1997

@uref{http://www.research.att.com/sw/tools/cdt/cdt.ps}

@item

David G. Korn and Kiem-Phong Vo, ``Sfio: Safe/Fast String/File IO'',

Proceedings of the Summer '91 Usenix Conference, pp.  235-256, 1991.

@uref{http://citeseer.nj.nec.com/korn91sfio.html}

@end itemize

Source code should be indented according to the GNU Coding Standards,

with spaces not tabs. For example, by using the @code{indent} command:

@example

indent -gnu -nut *.c *.h

@end example

@noindent

The @code{-nut} option converts tabs into spaces.

@node Background and Preparation, Choice of Algorithms, Standards and conventions, Design

@section Background and Preparation

Before implementing something be sure to research the subject

thoroughly!  This will save a lot of time in the long-run.  The two most

important steps are,

@enumerate

@item

to determine whether there is already a free library (GPL or

GPL-compatible) which does the job.  If so, there is no need to

reimplement it.  Carry out a search on Netlib, GAMs, na-net,

sci.math.num-analysis and the web in general. This should also provide

you with a list of existing proprietary libraries which are relevant,

keep a note of these for future reference in step 2.

@item 

make a comparative survey of existing implementations in the

commercial/free libraries. Examine the typical APIs, methods of

communication between program and subroutine, and classify them so that

you are familiar with the key concepts or features that an

implementation may or may not have, depending on the relevant tradeoffs

chosen.  Be sure to review the documentation of existing libraries for

useful references.

@item

read up on the subject and determine the state-of-the-art.  Find the

latest review papers.  A search of the following journals should be

undertaken.

@itemize @w{}

@item ACM Transactions on Mathematical Software

@item Numerische Mathematik

@item Journal of Computation and Applied Mathematics

@item Computer Physics Communications

@item SIAM Journal of Numerical Analysis

@item SIAM Journal of Scientific Computing

@end itemize

@end enumerate

@noindent

Keep in mind that GSL is not a research project.  Making a good

implementation is difficult enough, without also needing to invent new

algorithms.  We want to implement existing algorithms whenever

possible. Making minor improvements is ok, but don't let it be a

time-sink.

@node Choice of Algorithms, Documentation, Background and Preparation, Design

@section Choice of Algorithms

Whenever possible choose algorithms which scale well and always remember

to handle asymptotic cases.  This is particularly relevant for functions

with integer arguments.  It is tempting to implement these using the

simple @math{O(n)} algorithms used to define the functions, such as the

many recurrence relations found in Abramowitz and Stegun.  While such

methods might be acceptable for @math{n=O(10-100)} they will not be

satisfactory for a user who needs to compute the same function for

@math{n=1000000}.

Similarly, do not make the implicit assumption that multivariate data

has been scaled to have components of the same size or O(1).  Algorithms

should take care of any necessary scaling or balancing internally, and

use appropriate norms (e.g. |Dx| where D is a diagonal scaling matrix,

rather than |x|).

@node Documentation, Namespace, Choice of Algorithms, Design

@section Documentation

Documentation: the project leaders should give examples of how things

are to be documented.  High quality documentation is absolutely

mandatory, so documentation should introduce the topic, and give careful

reference for the provided functions. The priority is to provide

reference documentation for each function. It is not necessary to

provide tutorial documentation.

Use free software, such as GNU Plotutils, to produce the graphs in the

manual.

Some of the graphs have been made with gnuplot which is not truly free

(or GNU) software, and some have been made with proprietary

programs. These should be replaced with output from GNU plotutils.

When citing references be sure to use the standard, definitive and

best reference books in the field, rather than lesser known text-books

or introductory books which happen to be available (e.g. from

undergraduate studies).  For example, references concerning algorithms

should be to Knuth, references concerning statistics should be to

Kendall & Stuart, references concerning special functions should be to

Abramowitz & Stegun (Handbook of Mathematical Functions AMS-55), etc.

Wherever possible refer to Abramowitz & Stegun rather than other

reference books because it is a public domain work, so it is

inexpensive and freely redistributable.

The standard references have a better chance of being available in an

accessible library for the user.  If they are not available and the user

decides to buy a copy in order to look up the reference then this also

gives them the best quality book which should also cover the largest

number of other references in the GSL Manual.  If many different books

were to be referenced this would be an expensive and inefficient use of

resources for a user who needs to look up the details of the algorithms.

Reference books also stay in print much longer than text books, which

are often out-of-print after a few years.

Similarly, cite original papers wherever possible.  Be sure to keep

copies of these for your own reference (e.g. when dealing with bug

reports) or to pass on to future maintainers.

If you need help in tracking down references, ask on the

@code{gsl-discuss} mailing list.  There is a group of volunteers with

access to good libraries who have offered to help GSL developers get

copies of papers.

@c [JT section: written by James Theiler

@c And we furthermore promise to try as hard as possible to document

@c the software: this will ideally involve discussion of why you might want

@c to use it, what precisely it does, how precisely to invoke it, 

@c how more-or-less it works, and where we learned about the algorithm,

@c and (unless we wrote it from scratch) where we got the code.

@c We do not plan to write this entire package from scratch, but to cannibalize

@c existing mathematical freeware, just as we expect our own software to

@c be cannibalized.]

To write mathematics in the texinfo file you can use the @code{@@math}

command with @emph{simple} TeX commands. These are automatically

surrounded by @code{$...$} for math mode. For example,

@example

to calculate the coefficient @@math@{\alpha@} use the function...

@end example

@noindent

will be correctly formatted in both online and TeX versions of the

documentation.

Note that you cannot use the special characters @{ and @}

inside the @code{@@math} command because these conflict between TeX

and Texinfo.  This is a problem if you want to write something like

@code{\sqrt@{x+y@}}.  

To work around it you can precede the math command with a special

macro @code{@@c} which contains the explicit TeX commands you want to

use (no restrictions), and put an ASCII approximation into the

@code{@@math} command (you can write @code{@@@{} and

@code{@@@}} there for the left and right braces).  The explicit TeX

commands are used in the TeX output and the argument of @code{@@math}

in the plain info output.  

Note that the @code{@@c@{@}} macro must go at the end of the

preceding line, because everything else after it is ignored---as far

as texinfo is concerned it's actually a 'comment'. The comment

command @@c has been modified to capture a TeX expression which is

output by the next @@math command. For ordinary comments use the @@comment

command.

For example,

@example

this is a test @@c@{$\sqrt@{x+y@}$@}

@@math@{\sqrt@@@{x+y@@@}@}

@end example

@noindent

is equivalent to @code{this is a test $\sqrt@{x+y@}$} in plain TeX

and @code{this is a test @@math@{\sqrt@@@{x+y@@@}@}} in Info.  

It looks nicer if some of the more cryptic TeX commands are given

a C-style ascii version, e.g.

@example

for @@c@{$x \ge y$@}

@@math@{x >= y@}

@end example

@noindent

will be appropriately displayed in both TeX and Info.

@node Namespace, Header files, Documentation, Design

@section Namespace

Use @code{gsl_} as a prefix for all exported functions and variables.

Use @code{GSL_} as a prefix for all exported macros.

All exported header files should have a filename with the prefix @code{gsl_}.

All installed libraries should have a name like libgslhistogram.a

Any installed executables (utility programs etc) should have the prefix

@code{gsl-} (with a hyphen, not an underscore).

All function names, variables, etc.@: should be in lower case.  Macros and

preprocessor variables should be in upper case.

Some common conventions in variable and function names:

@table @code

@item p1

plus 1, e.g. function @code{log1p(x)} or a variable like @code{kp1}, @math{=k+1}.

@item m1

minus 1, e.g. function @code{expm1(x)} or a variable like @code{km1}, @math{=k-1}.

@end table

@node Header files, Target system, Namespace, Design

@section Header files

Installed header files should be idempotent, i.e. surround them by the

preprocessor conditionals like the following,

@example

#ifndef __GSL_HISTOGRAM_H__

#define __GSL_HISTOGRAM_H__

...

#endif /* __GSL_HISTOGRAM_H__ */

@end example

@node Target system, Function Names, Header files, Design

@section Target system

The target system is ANSI C, with a full Standard C Library, and IEEE

arithmetic.

@node Function Names, Object-orientation, Target system, Design

@section Function Names

Each module has a name, which prefixes any function names in that

module, e.g. the module gsl_fft has function names like

gsl_fft_init. The modules correspond to subdirectories of the library

source tree.

@node Object-orientation, Comments, Function Names, Design

@section Object-orientation

The algorithms should be object oriented, but only to the extent that is

easy in portable ANSI C.  The use of casting or other tricks to simulate

inheritance is not desirable, and the user should not have to be aware

of anything like that.  This means many types of patterns are ruled

out.  However, this is not considered a problem -- they are too

complicated for the library.  

Note: it is possible to define an abstract base class easily in C, using

function pointers.  See the rng directory for an example. 

When reimplementing public domain Fortran code, please try to introduce

the appropriate object concepts as structs, rather than translating the

code literally in terms of arrays.  The structs can be useful just

within the file, you don't need to export them to the user.

For example, if a Fortran program repeatedly uses a subroutine like,

@example

SUBROUTINE  RESIZE (X, K, ND, K1)

@end example

@noindent

where X(K,D) represents a grid to be resized to X(K1,D) you can make

this more readable by introducing a struct,

@smallexample

struct grid @{

    int nd;  /* number of dimensions */

    int k;   /* number of bins */

    double * x;   /* partition of axes, array of size x[k][nd] */

@}

void

resize_grid (struct grid * g, int k_new)

@{

...

@}

@end smallexample

@noindent

Similarly, if you have a frequently recurring code fragment within a

single file you can define a static or static inline function for it.

This is typesafe and saves writing out everything in full.

@node Comments, Minimal structs, Object-orientation, Design

@section Comments

Follow the GNU Coding Standards.  A relevant quote is,

``Please write complete sentences and capitalize the first word.  If a

lower-case identifier comes at the beginning of a sentence, don't

capitalize it!  Changing the spelling makes it a different identifier.

If you don't like starting a sentence with a lower case letter, write

the sentence differently (e.g., "The identifier lower-case is ...").''

@node Minimal structs, Algorithm decomposition, Comments, Design

@section Minimal structs

We prefer to make structs which are @dfn{minimal}.  For example, if a

certain type of problem can be solved by several classes of algorithm

(e.g. with and without derivative information) it is better to make

separate types of struct to handle those cases.  i.e. run time type

identification is not desirable.

@node Algorithm decomposition, Memory allocation and ownership, Minimal structs, Design

@section Algorithm decomposition

Iterative algorithms should be decomposed into an INITIALIZE, ITERATE,

TEST form, so that the user can control the progress of the iteration

and print out intermediate results.  This is better than using

call-backs or using flags to control whether the function prints out