gsl-design.texi

math library from gnu

achieve this, so prioritize testing on the critical parts and use
inspection for the rest.  Test all the error conditions by explicitly
provoking them, because we consider it a serious defect if the function
does not return an error for an invalid parameter. N.B. Don't bother to
test for null pointers -- it's sufficient for the library to segfault if
the user provides an invalid pointer.

The tests should be deterministic.  Use the @code{gsl_test} functions
provided to perform separate tests for each feature with a separate
output PASS/FAIL line, so that any failure can be uniquely identified.

Use realistic test cases with 'high entropy'.  Tests on simple values
such as 1 or 0 may not reveal bugs.  For example, a test using a value
of @math{x=1} will not pick up a missing factor of @math{x} in the code.
Similarly, a test using a value of @math{x=0} will not pick any missing
terms involving @math{x} in the code.  Use values like @math{2.385} to
avoid silent failures. 

If your test uses multiple values make sure there are no simple
relations between them that could allow bugs to be missed through silent
cancellations.

If you need some random floats to put in the test programs use @code{od -f
/dev/random} as a source of inspiration.

Don't use @code{sprintf} to create output strings in the tests.  It can
cause hard to find bugs in the test programs themselves.  The functions
@code{gsl_test_...}  support format string arguments so use these
instead.

@node Compilation, Thread-safety, Test suites, Design
@section Compilation

Make sure everything compiles cleanly.  Use the strict compilation
options for extra checking.

@smallexample
make CFLAGS="-ansi -pedantic -Werror -W -Wall -Wtraditional -Wconversion 
  -Wshadow -Wpointer-arith -Wcast-qual -Wcast-align -Wwrite-strings 
  -Wstrict-prototypes -fshort-enums -fno-common -Wmissing-prototypes 
  -Wnested-externs -Dinline= -g -O4"
@end smallexample

@noindent
Also use @code{checkergcc} to check for memory problems on the stack and
the heap.  It's the best memory checking tool.  If checkergcc isn't
available then Electric Fence will check the heap, which is better than
no checking.

There is a new tool @code{valgrind} for checking memory access.  Test
the code with this as well.

Make sure that the library will also compile with C++ compilers
(g++).  This should not be too much of a problem if you have been writing
in ANSI C.

@node Thread-safety, Legal issues, Compilation, Design
@section Thread-safety

The library should be usable in thread-safe programs.  All the functions
should be thread-safe, in the sense that they shouldn't use static
variables.

We don't require everything to be completely thread safe, but anything
that isn't should be obvious.  For example, some global variables are
used to control the overall behavior of the library (range-checking
on/off, function to call on fatal error, etc).  Since these are accessed
directly by the user it is obvious to the multi-threaded programmer that
they shouldn't be modified by different threads.

There is no need to provide any explicit support for threads
(e.g. locking mechanisms etc), just to avoid anything which would make
it impossible for someone to call a GSL routine from a multithreaded
program.


@node Legal issues, Non-UNIX portability, Thread-safety, Design
@section Legal issues

@itemize @bullet
@item
Each contributor must make sure her code is under the GNU General Public
License (GPL).   This means getting a disclaimer from your employer.
@item
We must clearly understand ownership of existing code and algorithms.
@item
Each contributor can retain ownership of their code, or sign it over to
FSF as they prefer. 

There is a standard disclaimer in the GPL (take a look at it).  The more
specific you make your disclaimer the more likely it is that it will be
accepted by an employer.  For example,

@smallexample
Yoyodyne, Inc., hereby disclaims all copyright interest in the software
`GNU Scientific Library - Legendre Functions' (routines for computing
legendre functions numerically in C) written by James Hacker.

<signature of Ty Coon>, 1 April 1989
Ty Coon, President of Vice
@end smallexample

@item 
Obviously: don't use or translate non-free code. 

In particular don't copy or translate code from @cite{Numerical Recipes}
or @cite{ACM TOMS}.

Numerical Recipes is under a strict license and is not free software.
The publishers Cambridge University Press claim copyright on all aspects
of the book and the code, including function names, variable names and
ordering of mathematical subexpressions.  Routines in GSL should not
refer to Numerical Recipes or be based on it in any way.  

The ACM algorithms published in TOMS (Transactions on Mathematical
Software) are not public domain, even though they are distributed on the
internet -- the ACM uses a special non-commercial license which is not
compatible with the GPL. The details of this license can be found on the
cover page of ACM Transactions on Mathematical Software or on the ACM
Website.

Only use code which is explicitly under a free license: GPL or Public
Domain.  If there is no license on the code then this does not mean it
is public domain -- an explicit statement is required. If in doubt check
with the author.

@item
I @strong{think} one can reference algorithms from classic books on
numerical analysis (BJG: yes, provided the code is an independent
implementation and not copied from any existing software.  For
example, it would be ok to read the papers in ACM TOMS and make an
independent implementation from their description).
@end itemize

@node Non-UNIX portability, Compatibility with other libraries, Legal issues, Design
@section Non-UNIX portability

There is good reason to make this library work on non-UNIX systems.  It
is probably safe to ignore DOS and only worry about windows95/windowsNT
portability (so filenames can be long, I think).

On the other hand, nobody should be forced to use non-UNIX systems for
development.

The best solution is probably to issue guidelines for portability, like
saying "don't use XYZ unless you absolutely have to".  Then the Windows
people will be able to do their porting.

@node Compatibility with other libraries, Parallelism, Non-UNIX portability, Design
@section Compatibility with other libraries

We do not regard compatibility with other numerical libraries as a
priority.

However, other libraries, such as Numerical Recipes, are widely used.
If somebody writes the code to allow drop-in replacement of these
libraries it would be useful to people.  If it is done, it would be as a
separate wrapper that can be maintained and shipped separately.

There is a separate issue of system libraries, such as BSD math library
and functions like @code{expm1}, @code{log1p}, @code{hypot}.  The
functions in this library are available on nearly every platform (but
not all).  

In this case, it is best to write code in terms of these native
functions to take advantage of the vendor-supplied system library (for
example log1p is a machine instruction on the Intel x86). The library
also provides portable implementations e.g. @code{gsl_hypot} which are
used as an automatic fall back via autoconf when necessary. See the
usage of @code{hypot} in @file{gsl/complex/math.c}, the implementation
of @code{gsl_hypot} and the corresponding parts of files
@file{configure.in} and @file{config.h.in} as an example.

@node Parallelism, Precision, Compatibility with other libraries, Design
@section Parallelism

We don't intend to provide support for parallelism within the library
itself. A parallel library would require a completely different design
and would carry overhead that other applications do not need.

@node Precision, Miscellaneous, Parallelism, Design
@section Precision

For algorithms which use cutoffs or other precision-related terms please
express these in terms of @code{GSL_DBL_EPSILON} and @code{GSL_DBL_MIN}, or powers or
combinations of these.  This makes it easier to port the routines to
different precisions.

@node Miscellaneous,  , Precision, Design
@section Miscellaneous

Don't use the letter @code{l} as a variable name --- it is difficult to
distinguish from the number @code{1}. (This seems to be a favorite in
old Fortran programs).

Final tip: one perfect routine is better than any number of routines
containing errors.

@node Bibliography, Copying, Design, Top
@chapter Bibliography 

@section General numerics

@itemize

@item
@cite{Numerical Computation} (2 Volumes) by C.W. Ueberhuber,
Springer 1997,  ISBN 3540620583  (Vol 1) and  ISBN 3540620575  (Vol 2).

@item
@cite{Accuracy and Stability of Numerical Algorithms} by  N.J. Higham, 
SIAM,  ISBN 0898715210.

@item
@cite{Sources and Development of Mathematical Software} edited by W.R. Cowell,
Prentice Hall, ISBN 0138235015.

@item
@cite{A Survey of Numerical Mathematics (2 vols)} by D.M. Young and R.T. Gregory,
 ISBN 0486656918, ISBN 0486656926.

@item
@cite{Methods and Programs for Mathematical Functions} by Stephen L. Moshier,
Hard to find (ISBN 13578980X or 0135789982, possibly others).

@item
@cite{Numerical Methods That Work} by Forman S. Acton,
 ISBN 0883854503.

@item
@cite{Real Computing Made Real: Preventing Errors in Scientific and Engineering Calculations} by Forman S. Acton,
 ISBN 0486442217. 
@end itemize

@section Reference

@itemize
@item
@cite{Handbook of Mathematical Functions} edited by Abramowitz & Stegun,
Dover,  ISBN 0486612724.

@item
@cite{The Art of Computer Programming} (3rd Edition, 3 Volumes) by D. Knuth,
Addison Wesley,  ISBN 0201485419.
@end itemize

@section Subject specific

@itemize
@item
@cite{Matrix Computations} (3rd Ed) by G.H. Golub, C.F. Van Loan,
Johns Hopkins University Press 1996,  ISBN 0801854148.

@item
@cite{LAPACK Users' Guide} (3rd Edition),
SIAM 1999,  ISBN 0898714478.

@item
@cite{Treatise on the Theory of Bessel Functions 2ND Edition} by G N Watson,
 ISBN 0521483913.

@item
@cite{Higher Transcendental Functions satisfying nonhomogenous linear differential equations} by A W Babister,
 ISBN 1114401773.

@end itemize

@node Copying, GNU Free Documentation License, Bibliography, Top
@unnumbered Copying

   The subroutines and source code in the @value{GSL} package are "free";
this means that everyone is free to use them and free to redistribute
them on a free basis.  The @value{GSL}-related programs are not in the
public domain; they are copyrighted and there are restrictions on their
distribution, but these restrictions are designed to permit everything
that a good cooperating citizen would want to do.  What is not allowed
is to try to prevent others from further sharing any version of these
programs that they might get from you.

   Specifically, we want to make sure that you have the right to give
away copies of the programs that relate to @value{GSL}, that you receive
source code or else can get it if you want it, that you can change these
programs or use pieces of them in new free programs, and that you know
you can do these things.

   To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights.  For example, if you distribute
copies of the @value{GSL}-related code, you must give the recipients all
the rights that you have.  You must make sure that they, too, receive or
can get the source code.  And you must tell them their rights.

   Also, for our own protection, we must make certain that everyone
finds out that there is no warranty for the programs that relate to
@value{GSL}.  If these programs are modified by someone else and passed
on, we want their recipients to know that what they have is not what we
distributed, so that any problems introduced by others will not reflect
on our reputation.

   The precise conditions of the licenses for the programs currently
being distributed that relate to @value{GSL} are found in the General
Public Licenses that accompany them.

@node GNU Free Documentation License,  , Copying, Top
@unnumbered GNU Free Documentation License
@include fdl.texi

@c @printindex cp

@c @node Function Index
@c @unnumbered Function Index

@c @printindex fn

@c @node Variable Index
@c @unnumbered Variable Index

@c @printindex vr

@c @node Type Index
@c @unnumbered Type Index

@c @printindex tp

@bye