gsl-design.texi

开放gsl矩阵运算

@node Using Return Values, Variable Names, Persistence, Design
@section Using Return Values

Always assign a return value to a variable before using it.  This allows
easier debugging of the function, and inspection and modification of the
return value.  If the variable is only needed temporarily then enclose
it in a suitable scope.

For example, instead of writing,

@example
a = f(g(h(x,y)))
@end example
@noindent
use temporary variables to store the intermediate values,
@example
@{
  double u = h(x,y);
  double v = g(u);
  a = f(v);
@}
@end example
@noindent
These can then be inspected more easily in the debugger, and breakpoints
can be placed more precisely.  The compiler will eliminate the temporary
variables automatically when the program is compiled with optimization.

@node Variable Names, Datatype widths, Using Return Values, Design
@section Variable Names

Try to follow existing conventions for variable names,

@table @code
@item dim
number of dimensions
@item w
pointer to workspace 
@item state
pointer to state variable (use @code{s} if you need to save characters)
@item result
pointer to result (output variable)
@item abserr
absolute error 
@item relerr
relative error
@item size
the size of an array or vector e.g. double array[size] 
@item stride
the stride of a vector
@item size1
the number of rows in a matrix
@item size2
the number of columns in a matrix
@item n
general integer number, e.g. number of elements of array, in fft, etc
@item r
random number generator (gsl_rng)
@end table

@node Datatype widths, size_t, Variable Names, Design
@section Datatype widths

Be aware that in ANSI C the type @code{int} is only guaranteed to
provide 16-bits. It may provide more, but is not guaranteed to.
Therefore if you require 32 bits you must use @code{long int}, which
will have 32 bits or more.  Of course, on many platforms the type
@code{int} does have 32 bits instead of 16 bits but we have to code to
the ANSI standard rather than a specific platform.

@node size_t, Arrays vs Pointers, Datatype widths, Design
@section size_t

All objects (blocks of memory, etc) should be measured in terms of a
@code{size_t} type.  Therefore any iterations (e.g. @code{for(i=0; i<N;
i++)}) should also use an index of type @code{size_t}.  If you need to
write a descending loop you have to be careful because @code{size_t} is
unsigned, so instead of

@example
for (i = N - 1; i >= 0; i--) @{ ... @}
@end example
@noindent
use something like

@example
for (i = N; i > 0 && i--;) @{ ... @}
@end example
@noindent
to avoid problems with wrap-around at @code{i=0}.

If you really want to avoid confusion use a separate variable to invert
the loop order,
@example
for (i = 0; i < N; i++) @{ j = N - i; ... @}
@end example


@node Arrays vs Pointers, Constness, size_t, Design
@section Arrays vs Pointers

A function can be declared with either pointer arguments or array
arguments.  The C standard considers these to be equivalent. However, it
is useful to distinguish between the case of a pointer, representing a
single object which is being modified, and an array which represents a
set of objects with unit stride (that are modified or not depending on
the presence of @code{const}).  For vectors, where the stride is not
required to be unity, the pointer form is preferred.

@example
/* real value, set on output */
int foo (double * x);                           

/* real vector, modified */
int foo (double * x, size_t stride, size_t n);  

/* constant real vector */
int foo (const double * x, size_t stride, size_t n);  

/* real array, modified */
int bar (double x[], size_t n);                 

/* real array, not modified */
int baz (const double x[], size_t n);           
@end example

@node Constness, Pseudo-templates, Arrays vs Pointers, Design
@section Constness

Use @code{const} in function prototypes wherever an object pointed to by
a pointer is constant (obviously).  For variables which are meaningfully
constant within a function/scope use @code{const} also.  This prevents
you from accidentally modifying a variable which should be constant
(e.g. length of an array, etc).  It can also help the compiler do
optimization.  These comments also apply to arguments passed by value
which should be made @code{const} when that is meaningful.

@node Pseudo-templates, Test suites, Constness, Design
@section Pseudo-templates

There are some pseudo-template macros available in @file{templates_on.h}
and @file{templates_off.h}.  See a directory link @file{block} for
details on how to use them.  Use sparingly, they are a bit of a
nightmare, but unavoidable in places.

In particular, the convention is: templates are used for operations on
"data" only (vectors, matrices, statistics, sorting).  This is intended
to cover the case where the program must interface with an external
data-source which produces a fixed type. e.g. a big array of char's
produced by an 8-bit counter.

All other functions can use double, for floating point, or the
appropriate integer type for integers (e.g. unsigned long int for random
numbers).  It is not the intention to provide a fully templated version
of the library. 

That would be "putting a quart into a pint pot". To summarize, almost
everything should be in a "natural type" which is appropriate for
typical usage, and templates are there to handle a few cases where it is
unavoidable that other data-types will be encountered.

For floating point work "double" is considered a "natural type".  This
sort of idea is a part of the C language.

@node Test suites, Compilation, Pseudo-templates, Design
@section Test suites

The implementor of each library should provide a reasonable test suite
for that library.

The test suite should be a program that uses the library and checks the
result against known results, or invokes the library several times and
does a statistical analysis on the results (for example in the case of
random number generators).

Ideally the one test program per directory should aim for 100% path
coverage of the code.  Obviously it would be a lot of work to really
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.

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

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

@example
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 example
@noindent
Also use 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 nothing.

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).
@item
We must understand ownership of existing code and algorithms.
@itemize @minus
@item
Obviously: don't use or translate non-free code. Such as: Numerical
Recipes, ACM TOMS.  

Note that the ACM algorithms 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 (see the Debian
Free Software Guidelines for details). If in doubt check with the
author.

@item
I @strong{think} one can reference algorithms from classic books on
numerical analysis.
@end itemize

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

We should also read up on what Cygnus is doing for their win32
portability.


@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, Miscellaneous, 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 Miscellaneous,  , Parallelism, 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).

@node Copying,  , Design, 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.

@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

@c -@shortcontents
@contents
@bye