@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 subroutineFor example, partial differential equation solvers are often huge andvery specialized applications (since there are so many types of PDEs,types of solution, types of grid, etc).  This sort of thing shouldremain separate.  It is better to point people to the good applicationswhich exist.@item anything which is independent and useful separately.Arguably functions for manipulating date and time, or financialfunctions might be included in a "scientific" library.  However, thesesorts of modules could equally well be used independently in otherprograms, 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 LibrariesIn writing a numerical library there is a unavoidable conflict betweencompleteness and simplicity.  Completeness refers to the ability toperform operations on different objects so that the group is"closed". In mathematics objects can be combined and operated on in aninfinite number of ways.  For example, I can take the derivative of ascalar field wrt a vector and the derivative of a vector field wrt ascalar (along a path).There is a definite tendency to unconsciously try to reproduce all thesepossibilities in a numerical library, by adding new features one byone. After all, it is always easy enough to support just one morefeature.... so why not?Looking at the big picture, no-one would start out by saying "I want tobe able to represent every possible mathematical object and operationusing C structs" -- this is a strategy which is doomed to fail.  Thereis a limited amount of complexity which can be represented in aprogramming language like C.  Attempts to reproduce the complexity ofmathematics within such a language would just lead to a morass ofunmaintainable code.  However, it's easy to go down that road if youdon't think about it ahead of time.It is better to choose simplicity over completeness.  In designing newparts of the library keep modules independent where possible. Ifinterdependencies between modules are introduced be sure about where youare going to draw the line.Whenever possible choose algorithms which scale well and always rememberto handle asymptotic cases.  This is particularly relevant for functionswith integer arguments.  It is tempting to implement these using thesimple @math{O(n)} algorithms used to define the functions, such as themany recurrence relations found in Abramowitz and Stegun.  While suchmethods might be acceptable for @math{n=O(10-100)} they will not besatisfactory for a user who needs to compute the same function for@math{n=1000000}.@node Code Reuse, Standards and conventions, Design of  Numerical Libraries, Design@section Code ReuseIt is useful if people can grab a single source file and include it intheir own programs without needing the whole library.  Try to allowstandalone files like this whenever it is reasonable.  Obviously theuser might need to define a few macros, such as GSL_ERROR, to compilethe file but that is ok.  Examples where this can be done: grabbing asingle random number generator.@node Standards and conventions, Background and Preparation, Code Reuse, Design@section Standards and conventionsThe people who kick off this project should set the coding standards andconventions.  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 itemizeThe 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 thedefinitive reference and also in the public domain.If the project has a philosophy it is to "Think in C".  Since we areworking in C we should only do what is natural in C, rather than tryingto simulate features of other languages.  If there is something which isunnatural in C and has to be simulated then we avoid using it. If thismeans leaving something out of the library, or only offering a limitedversion then so be it.  It is not worthwhile making the libraryover-complicated.  There are numerical libraries in other languages, andif people need the features of those languages it would be sensible forthem to use the corresponding libraries, rather than coercing a Clibrary into doing that job.  It should be borne in mind at all time that C is a macro-assembler.  Ifyou are in doubt about something being too complicated ask yourself thequestion "Would I try to write this in macro-assembler?" If the answeris obviously "No" then do not try to include it in GSL. [BJG]It will be useful to read the following paper,@itemize @asis@item Kiem-Phong Vo, ``The Discipline and Method Architecture for ReusableLibraries'', Software - Practice & Experience, v.30, pp.107-128, 2000.@end itemize@noindentIt is available from@url{http://www.research.att.com/sw/tools/sfio/dm-spe.ps} or the earliertechnical report Kiem-Phong Vo, "An Architecture for Reusable Libraries"@url{http://citeseer.nj.nec.com/48973.html}.There are associated papers on Vmalloc, SFIO, and CDT which are alsorelevant to the design of portable C libraries.@itemize @asis@itemKiem-Phong Vo, ``Vmalloc: A General and Efficient MemoryAllocator''. Software Practice & Experience, 26:1--18, 1996.@url{http://www.research.att.com/sw/tools/vmalloc/vmalloc.ps}@itemKiem-Phong Vo. ``Cdt: A Container Data Type Library''. Soft. Prac. &Exp., 27:1177--1197, 1997@url{http://www.research.att.com/sw/tools/cdt/cdt.ps}@itemDavid G. Korn and Kiem-Phong Vo, ``Sfio: Safe/Fast String/File IO'',Proceedings of the Summer '91 Usenix Conference, pp.  235-256, 1991.@url{http://citeseer.nj.nec.com/korn91sfio.html}@end itemizeSource code should be indented according to the GNU Coding Standards,with spaces not tabs. For example, by using the @code{indent} command:@exampleindent -gnu -nut *.c *.h@end example@noindentThe @code{-nut} option converts tabs into spaces.@node Background and Preparation, Documentation, Standards and conventions, Design@section Background and PreparationBefore implementing something be sure to research the subjectthoroughly!  This will save a lot of time in the long-run.  The two mostimportant steps are,@enumerate@itemto determine whether there is already a free library (GPL orGPL-compatible) which does the job.  If so, there is no need toreimplement it.  Carry out a search on Netlib, GAMs, na-net,sci.math.num-analysis and the web in general. This should also provideyou 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 thecommercial/free libraries. Examine the typical APIs, methods ofcommunication between program and subroutine, and classify them so thatyou are familiar with the key concepts or features that animplementation may or may not have, depending on the relevant tradeoffschosen.  Be sure to review the documentation of existing libraries foruseful references.@itemread up on the subject and determine the state-of-the-art.  Find thelatest review papers.  A search of the following journals should beundertaken.@itemize @asis@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@node Documentation, Namespace, Background and Preparation, Design@section DocumentationDocumentation: the project leaders should give examples of how thingsare to be documented.  High quality documentation is absolutelymandatory, so documentation should introduce the topic, and give carefulreference for the provided functions. The priority is to providereference documentation for each function. It is not necessary toprovide tutorial documentation.Use free software, such as GNU Plotutils, to produce the graphs in themanual.Some of the graphs have been made with gnuplot which is not truly free(or GNU) software, and some have been made with proprietaryprograms. These should be replaced with output from GNU plotutils.When citing references be sure to use the standard, definitive and bestreference books in the field, rather than lesser known text-books orintroductory books which happen to be available (e.g. from undergraduatestudies).  For example, references concerning algorithms should be toKnuth, references concerning statistics should be to Kendall & Stuart,references concerning special functions should be to Abramowitz & Stegun(Handbook of Mathematical Functions AMS-55), etc.The standard references have a better chance of being available in anaccessible library for the user.  If they are not available and the userdecides to buy a copy in order to look up the reference then this alsogives them the best quality book which should also cover the largestnumber of other references in the GSL Manual.  If many different bookswere to be referenced this would be an expensive and inefficient use ofresources for a user who needs to look up the details of the algorithms.Reference books also stay in print much longer than text books, whichare often out-of-print after a few years.Similarly, cite original papers wherever possible.  Be sure to keepcopies of these for your own reference (e.g. when dealing with bugreports) 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 withaccess to good libraries who have offered to help GSL developers getcopies of papers.[JT section: written by James TheilerAnd we furthermore promise to try as hard as possible to documentthe software: this will ideally involve discussion of why you might wantto use it, what precisely it does, how precisely to invoke it, how more-or-less it works, and where we learned about the algorithm,and (unless we wrote it from scratch) where we got the code.We do not plan to write this entire package from scratch, but to cannibalizeexisting mathematical freeware, just as we expect our own software tobe cannibalized.]@node Namespace, Header files, Documentation, Design@section NamespaceUse @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.aAny 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 andpreprocessor variables should be in upper case.@node Header files, Target system, Namespace, Design@section Header filesInstalled header files should be idempotent, i.e. surround them by thepreprocessor 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 systemThe target system is ANSI C, with a full Standard C Library, and IEEEarithmetic.@node Function Names, Object-orientation, Target system, Design@section Function NamesEach module has a name, which prefixes any function names in thatmodule, e.g. the module gsl_fft has function names likegsl_fft_init. The modules correspond to subdirectories of the librarysource tree.@node Object-orientation, Comments, Function Names, Design@section Object-orientationThe algorithms should be object oriented, but only to the extent that iseasy in portable ANSI C.  The use of casting or other tricks to simulateinheritance is not desirable, and the user should not have to be awareof anything like that.  This means many types of patterns are ruledout.  However, this is not considered a problem -- they are toocomplicated for the library.  Note: it is possible to define an abstract base class easily in C, usingfunction pointers.  See the rng directory for an example. When reimplementing public domain fortran code, please try to introducethe appropriate object concepts as structs, rather than translating thecode literally in terms of arrays.  The structs can be useful justwithin the file, you don't need to export them to the user.For example, if a fortran program repeatedly uses a subroutine like,@exampleSUBROUTINE  RESIZE (X, K, ND, K1)@end example@noindentwhere X(K,D) represents a grid to be resized to X(K1,D) you can makethis more readable by introducing a struct,@smallexamplestruct grid @{    int nd;  /* number of dimensions */    int k;   /* number of bins */    double * x;   /* partition of axes, array of size x[k][nd] */@}voidresize_grid (struct grid * g, int k_new)@{...@}@end smallexample@noindent