Mark Galassi James Theiler Brian Gough
There is a need for scientists and engineers to have a numerical librarythat:
- is free (in the sense of freedom, not in the sense of gratis; see theGNU General Public License), so that people can use that library,redistribute it, modify it ..
- is written in C using modern coding conventions, calling conventions,scoping ..
- is clearly and pedagogically documented; preferably with TeXinfo, so asto allow online info, WWW and TeX output.
- uses top quality state-of-the-art algorithms.
- is portable and configurable using autoconf and automake.
- basically, is GNUlitically correct.
Note: as of summer 2018, Rogue Wave. IMSL is no longer available directly from Intel. It can be obtained directly from Rogue Wave or Rogue Wave resellers. Overview This application note illustrates steps to use the latest version of Intel® MKL with Intel® Visual Fortran Composer XE 2011 for Windows with IMSL Fortran Numerical Libraries 6.0. on Intel® architecture systems under Microsoft. Now that you have successfully installed the IMSL Fortran Numerical Library and have become familiar with the documentation, you can now put the IMSL Fortran Numerical Library to some use. For that purpose, we will provide two examples. Example 1 uses a regular text editor and the command line in a linux environment.
There are strengths and weaknesses with existing libraries:
Netlib (http://www.netlib.org/) is probably the most advanced setof numerical algorithms available on the net, maintained by AT&T.Unfortunately most of the software is written in Fortran, with strangecalling conventions in many places. It is also not very well collected,so it is a lot of work to get started with netlib.
GAMS (http://gams.nist.gov/) is an extremely well organized setof pointers to scientific software, but like netlib, the individualroutines vary in their quality and their level of documentation.
Numerical Recipes (http://www.nr.com,http://cfata2.harvard.edu/nr/) is an excellent book: it explains thealgorithms in a very clear way. Unfortunately the authors released thesource code under a license which allows you to use it, but prevents youfrom re-distributing it. Thus Numerical Recipes is not free inthe sense of freedom. On top of that, the implementation suffersfrom fortranitis and otherlimitations. [http://www.lysator.liu.se/c/num-recipes-in-c.html]
SLATEC is a large public domain collection of numerical routinesin Fortran written under a Department of Energy program in the1970's. The routines are well tested and have a reasonable overalldesign (given the limitations of that era). GSL should aim to be amodern version of SLATEC.
NSWC is the Naval Surface Warfare Center numerical library. Itis a large public-domain Fortran library, containing a lot ofhigh-quality code. Documentation for the library is hard to find, onlya few photocopies of the printed manual are still in circulation.
NAG and IMSL both sell high-quality libraries which areproprietary. The NAG library is more advanced and has wider scope thanIMSL. The IMSL library leans more towards ease-of-use and makesextensive use of variable length argument lists to emulate 'defaultarguments'.
ESSL and SCSL are proprietary libraries from IBM and SGI.
Forth Scientific Library [see the URLhttp://www.taygeta.com/fsl/sciforth.html]. Mainly of interest to Forthusers.
Numerical Algorithms with C G. Engeln-Mullges, F. Uhlig. A nicenumerical library written in ANSI C with an accompanyingtextbook. Source code is available but the library is not free software.
NUMAL A C version of the NUMAL library has been written byH.T. Lau and is published as a book and disk with the title 'A NumericalLibrary in C for Scientists and Engineers'. Source code is available butthe library is not free software.
Imsl Fortran Library Download Windows 7
C Mathematical Function Handbook by Louis Baker. A library offunction approximations and methods corresponding to those in the'Handbook of Mathematical Functions' by Abramowitz and Stegun. Sourcecode is available but the library is not free software.
Imsl Fortran Download
CCMATH by Daniel A. Atkinson. A C numerical library coveringsimilar areas to GSL. The code is quite terse. Earlier versions wereunder the GPL but unfortunately it has changed to the LGPL in recentversions.
CEPHES A useful collection of high-quality special functionswritten in C. Not GPL'ed.
WNLIB A small collection of numerical routines written in C byWill Naylor. Public domain.
Imsl Fortran Numerical Library
MESHACH A comprehensive matrix-vector linear algebra librarywritten in C. Freely available but not GPL'ed (non-commercial license).
CERNLIB is a large high-quality Fortran library developed at CERNover many years. It was originally non-free software but has recentlybeen released under the GPL.
COLT is a free numerical library in Java developed at CERN byWolfgang Hoschek. It is under a BSD-style license.
The long-term goal will be to provide a framework to which the realnumerical experts (or their graduate students) will contribute.
The GSL team welcomes new contributions to enhance the functionality ofthe library. Much emphasis is placed on ensuring the stability of theexisting functions, library consistency, and fixing any reported bugs.Potential contributors are encouraged to gain familiarity with thelibrary by investigating and fixing known problems listed in thebug tracker on the GSL savannah page.
Adding large amounts of new code is difficult because it leads todifferences in the maturity of different parts of the library. Tomaintain stability, any new functionality is encouraged aspackages, built on top of GSL and maintained independently by theauthor, as in other free software projects (such as the Perl CPANarchive and TeX CTAN archive, etc).
Imsl Fortran Numerical Library Download
Packages
Imsl Download
The design of GSL permits extensions to be used alongside the existinglibrary easily by simple linking. For example, additional random numbergenerators can be provided in a separate library:
Imsl Fortran Library Download App
Imsl Fortran Library Download Windows 10
The points below summarise the package design guidelines. These areintended to ensure that packages are consistent with GSL itself, to makelife easier for the end-user and make it possible to distribute popularwell-tested packages as part of the core GSL in future.
- Follow the GSL and GNU coding standards described in this documentThis means using the standard GNU packaging tools, such as Automake,providing documentation in Texinfo format, and a test suite. The testsuite should run using 'make check', and use the test functionsprovided in GSL to produce the output with
PASS:
/FAIL:
lines. It is not essential to use libtool since packages are likely tobe small, a static library is sufficient and simpler to build. - Use a new unique prefix for the package (do not use 'gsl_' -- this is reserved for internal use).For example, a package of additional random number generators might usethe prefix
rngextra
. - Use a meaningful version number which reflects the state of developmentGenerally,
0.x
are alpha versions, which provide no guarantees.Following that,0.9.x
are beta versions, which should be essentiallycomplete, subject only to minor changes and bug fixes. The first majorrelease is1.0
. Any version number of1.0
or highershould be suitable for production use with a well-defined API.The API must not change in a major release and should bebackwards-compatible in its behavior (excluding actual bug-fixes), sothat existing code do not have to be modified. Note that the APIincludes all exported definitions, including packages; not as part of the'core'. They are maintained separately by independent contributors.Use standard tools to make wrappers: swig, g-wrapWhat routines are implemented
Anything which is in any of the existing libraries. Obviously it makessense to prioritize and write code for the most important areas first.What routines are not implemented
- anything which already exists as a high-quality GPL'ed package.
- 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.
- 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.
Design of Numerical Libraries
In 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 with respect to a vector and the derivative of a vectorfield wrt a scalar (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.Code Reuse
It 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.Standards and conventions
The people who kick off this project should set the coding standards andconventions. In order of precedence the standards that we follow are,- We follow the GNU Coding Standards.
- We follow the conventions of the ANSI Standard C Library.
- We follow the conventions of the GNU C Library.
- We follow the conventions of the glib GTK support Library.
The references for these standards are the GNU Coding Standardsdocument, Harbison and Steele C: A Reference Manual, theGNU C Library Manual (version 2), and the Glib source code.For mathematical formulas, always follow the conventions in Abramowitz &Stegun, the 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,- Kiem-Phong Vo, 'The Discipline and Method Architecture for ReusableLibraries', Software - Practice & Experience, v.30, pp.107-128, 2000.
It is available fromhttp://www.research.att.com/sw/tools/sfio/dm-spe.ps or the earliertechnical report Kiem-Phong Vo, 'An Architecture for Reusable Libraries'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.- Kiem-Phong Vo, 'Vmalloc: A General and Efficient MemoryAllocator'. Software Practice & Experience, 26:1--18, 1996.http://www.research.att.com/sw/tools/vmalloc/vmalloc.ps
- Kiem-Phong Vo. 'Cdt: A Container Data Type Library'. Soft. Prac. &Exp., 27:1177--1197, 1997http://www.research.att.com/sw/tools/cdt/cdt.ps
- David G. Korn and Kiem-Phong Vo, 'Sfio: Safe/Fast String/File IO',Proceedings of the Summer '91 Usenix Conference, pp. 235-256, 1991.http://citeseer.nj.nec.com/korn91sfio.html
Source code should be indented according to the GNU Coding Standards,with spaces not tabs. For example, by using theindent
command:The-nut
option converts tabs into spaces.Background and Preparation
Before implementing something be sure to research the subjectthoroughly! This will save a lot of time in the long-run. The two mostimportant steps are,- to 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.
- 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.
- read up on the subject and determine the state-of-the-art. Find thelatest review papers. A search of the following journals should beundertaken.
- ACM Transactions on Mathematical Software
- Numerische Mathematik
- Journal of Computation and Applied Mathematics
- Computer Physics Communications
- SIAM Journal of Numerical Analysis
- SIAM Journal of Scientific Computing
Keep in mind that GSL is not a research project. Making a goodimplementation is difficult enough, without also needing to invent newalgorithms. We want to implement existing algorithms wheneverpossible. Making minor improvements is ok, but don't let it be atime-sink.Choice of Algorithms
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 O(n) algorithms used to define the functions, such as themany recurrence relations found in Abramowitz and Stegun. While suchmethods might be acceptable for n=O(10-100) they will not besatisfactory for a user who needs to compute the same function forn=1000000.Similarly, do not make the implicit assumption that multivariate datahas been scaled to have components of the same size or O(1). Algorithmsshould take care of any necessary scaling or balancing internally, anduse appropriate norms (e.g. |Dx| where D is a diagonal scaling matrix,rather than |x|).Documentation
Documentation: 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 thegsl-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.]Namespace
Usegsl_
as a prefix for all exported functions and variables.UseGSL_
as a prefix for all exported macros.All exported header files should have a filename with the prefixgsl_
.All installed libraries should have a name like libgslhistogram.aAny installed executables (utility programs etc) should have the prefixgsl-
(with a hyphen, not an underscore).All function names, variables, etc should be in lower case. Macros andpreprocessor variables should be in upper case.Header files
Installed header files should be idempotent, i.e. surround them by thepreprocessor conditionals like the following,Target system
The target system is ANSI C, with a full Standard C Library, and IEEEarithmetic.Function Names
Each 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.Object-orientation
The 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,where X(K,D) represents a grid to be resized to X(K1,D) you can makethis more readable by introducing a struct,Similarly, if you have a frequently recurring code fragment within asingle file you can define a static or static inline function for it.This is typesafe and saves writing out everything in full.Comments
Follow the GNU Coding Standards. A relevant quote is,'Please write complete sentences and capitalize the first word. If alower-case identifier comes at the beginning of a sentence, don'tcapitalize it! Changing the spelling makes it a different identifier.If you don't like starting a sentence with a lower case letter, writethe sentence differently (e.g., 'The identifier lower-case is ..').'Minimal structs
We prefer to make structs which are minimal. For example, if acertain type of problem can be solved by several classes of algorithm(e.g. with and without derivative information) it is better to makeseparate types of struct to handle those cases. i.e. run time typeidentification is not desirable.Algorithm decomposition
Iterative algorithms should be decomposed into an INITIALIZE, ITERATE,TEST form, so that the user can control the progress of the iterationand print out intermediate results. This is better than usingcall-backs or using flags to control whether the function prints outintermediate results. In fact, call-backs should not be used -- if theyseem necessary then it's a sign that the algorithm should be broken downfurther into individual components so that the user has complete controlover them.For example, when solving a differential equation the user may need tobe able to advance the solution by individual steps, while tracking arealtime process. This is only possible if the algorithm is broken downinto step-level components. Higher level decompositions would not givesufficient flexibility.Memory allocation and ownership
Functions which allocate memory on the heap should end in _alloc(e.g. gsl_foo_alloc) and be deallocated by a corresponding _free function(gsl_foo_free).Be sure to free any memory allocated by your function if you have toreturn an error in a partially initialized object.Don't allocate memory 'temporarily' inside a function and then free itbefore the function returns. This prevents the user from controllingmemory allocation. All memory should be allocated and freed throughseparate functions and passed around as a 'workspace' argument. Thisallows memory allocation to be factored out of tight loops.Memory layout
We use flat blocks of memory to store matrices and vectors, not C-stylepointer-to-pointer arrays. The matrices are stored in row-major order-- i.e. the column index (second index) moves continuously through memory.Linear Algebra Levels
Functions using linear algebra are divided into two levels:For purely '1d' functions we use the C-style arguments (double *,stride, size) so that it is simpler to use the functions in a normal Cprogram, without needing to invoke all the gsl_vector machinery.The philosophy here is to minimize the learning curve. If someone onlyneeds to use one function, like an fft, they can do so without havingto learn about gsl_vector.This leads to the question of why we don't do the same for matrices.In that case the argument list gets too long and confusing, with(size1, size2, tda) for each matrix and potential ambiguities over rowvs column ordering. In this case, it makes sense to use gsl_vector andgsl_matrix, which take care of this for the user.So really the library has two levels -- a lower level based on C typesfor 1d operations, and a higher level based on gsl_matrix andgsl_vector for general linear algebra.Of course, it would be possible to define a vector version of thelower level functions too. So far we have not done that because it wasnot essential -- it could be done but it is easy enough to get byusing the C arguments, by typing v->data, v->stride, v->size instead.A gsl_vector version of low-level functions would mainly be aconvenience.Please use BLAS routines internally within the library whenever possiblefor efficiency.Exceptions and Error handling
The basic error handling procedure is the return code (see gsl_errno.hfor a list of allowed values). Use the GSL_ERROR macro to mark anerror. The current definition of this macro is not ideal but it can bechanged at compile time.You should always use the GSL_ERROR macro to indicate an error, ratherthan just returning an error code. The macro allows the user to traperrors using the debugger (by setting a breakpoint on the functiongsl_error).The only circumstances where GSL_ERROR should not be used are where thereturn value is 'indicative' rather than an error -- for example, theiterative routines use the return code to indicate the success orfailure of an iteration. By the nature of an iterative algorithm'failure' (a return code of GSL_CONTINUE) is a normal occurrence andthere is no need to use GSL_ERROR there.Be sure to free any memory allocated by your function if you return anerror (in particular for errors in partially initialized objects).Persistence
If you make an object foo which uses blocks of memory (e.g. Toontrack ezkeys grand piano keygen manager. vector,matrix, histogram) you can provide functions for reading and writingthose blocks,Only dump out the blocks of memory, not any associated parameters suchas lengths. The idea is for the user to build higher level input/outputfacilities using the functions the library provides. The fprintf/fscanfversions should be portable between architectures, while the binaryversions should be the 'raw' version of the data. Use the functionsorto do the actual reading and writing.Using Return Values
Always assign a return value to a variable before using it. This allowseasier debugging of the function, and inspection and modification of thereturn value. If the variable is only needed temporarily then encloseit in a suitable scope.For example, instead of writing,use temporary variables to store the intermediate values,These can then be inspected more easily in the debugger, and breakpointscan be placed more precisely. The compiler will eliminate the temporaryvariables automatically when the program is compiled with optimization.Variable Names
Try to follow existing conventions for variable names,int
andsize_t
. They are notinterchangeable.If you need to write a descending loop you have to be careful becausesize_t
is unsigned, so instead ofuse something liketo avoid problems with wrap-around ati=0
.If you really want to avoid confusion use a separate variable to invertthe loop order,Arrays vs Pointers
A function can be declared with either pointer arguments or arrayarguments. The C standard considers these to be equivalent. However, itis useful to distinguish between the case of a pointer, representing asingle object which is being modified, and an array which represents aset of objects with unit stride (that are modified or not depending onthe presence ofconst
). For vectors, where the stride is notrequired to be unity, the pointer form is preferred.Pointers
Avoid dereferencing pointers on the right-hand side of an expression wherepossible. It's better to introduce a temporary variable. This iseasier for the compiler to optimise and also more readable since itavoids confusion between the use of*
for multiplication anddereferencing.is better written as,Constness
Useconst
in function prototypes wherever an object pointed to bya pointer is constant (obviously). For variables which are meaningfullyconstant within a function/scope useconst
also. This preventsyou from accidentally modifying a variable which should be constant(e.g. length of an array, etc). It can also help the compiler dooptimization. These comments also apply to arguments passed by valuewhich should be madeconst
when that is meaningful.Pseudo-templates
There are some pseudo-template macros available in 'templates_on.h'and 'templates_off.h'. See a directory link 'block' fordetails on how to use them. Use sparingly, they are a bit of anightmare, but unavoidable in places.In particular, the convention is: templates are used for operations on'data' only (vectors, matrices, statistics, sorting). This is intendedto cover the case where the program must interface with an externaldata-source which produces a fixed type. e.g. a big array of char'sproduced by an 8-bit counter.All other functions can use double, for floating point, or theappropriate integer type for integers (e.g. unsigned long int for randomnumbers). It is not the intention to provide a fully templated versionof the library.That would be 'putting a quart into a pint pot'. To summarize, almosteverything should be in a 'natural type' which is appropriate fortypical usage, and templates are there to handle a few cases where it isunavoidable that other is considered a 'natural type'. Thissort of idea is a part of the C language.Arbitrary Constants
Avoid arbitrary constants.For example, don't hard code 'small' values like '1e-30', '1e-100' or10*GSL_DBL_EPSILON
into the routines. This is not appropriatefor a general purpose library.Compute values accurately using IEEE arithmetic. If errors arepotentially significant then error terms should be estimated reliablyand returned to the user, by analytically deriving an error propagationformula, not using guesswork.A careful consideration of the algorithm usually shows that arbitraryconstants are unnecessary, and represent an important parameter whichshould be accessible to the user.For example, consider the following code:This should be rewritten as,in order to allow the user to determine whether the residual is significant or not.The only place where it is acceptable to use constants likeGSL_DBL_EPSILON
is in function approximations, (e.g. taylorseries, asymptotic expansions, etc). In these cases it is not anarbitrary constant, but an inherent part of the algorithm.Test suites
The implementor of each module should provide a reasonable test suitefor the routines.The test suite should be a program that uses the library and checks theresult against known results, or invokes the library several times anddoes a statistical analysis on the results (for example in the case ofrandom number generators).Ideally the one test program per directory should aim for 100% pathcoverage of the code. Obviously it would be a lot of work to reallyachieve this, so prioritize testing on the critical parts and useinspection for the rest. Test all the error conditions by explicitlyprovoking them, because we consider it a serious defect if the functiondoes not return an error for an invalid parameter. N.B. Don't bother totest for null pointers -- it's sufficient for the library to segfault ifthe user provides an invalid pointer.The tests should be deterministic. Use thegsl_test
functionsprovided to perform separate tests for each feature with a separateoutput PASS/FAIL line, so that any failure can be uniquely identified.Use realistic test cases with 'high entropy'. Tests on simple valuessuch as 1 or 0 may not reveal bugs. For example, a test using a valueof x=1 will not pick up a missing factor of x in the code.Similarly, a test using a value of x=0 will not pick any missingterms involving x in the code. Use values like 2.385 toavoid silent failures.If your test uses multiple values make sure there are no simplerelations between them that could allow bugs to be missed through silentcancellations.If you need some random floats to put in the test programs useod -f/dev/random
as a source of inspiration.Don't usesprintf
to create output strings in the tests. It cancause hard to find bugs in the test programs themselves. The functionsgsl_test_..
support format string arguments so use theseinstead.Compilation
Make sure everything compiles cleanly. Use the strict compilationoptions for extra checking.Also usecheckergcc
to check for memory problems on the stack andthe heap. It's the best memory checking tool. If checkergcc isn'tavailable then Electric Fence will check the heap, which is better thanno checking.There is a new toolvalgrind
for checking memory access. Testthe 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 writingin ANSI C.Thread-safety
The library should be usable in thread-safe programs. All the functionsshould be thread-safe, in the sense that they shouldn't use staticvariables.We don't require everything to be completely thread safe, but anythingthat isn't should be obvious. For example, some global variables areused to control the overall behavior of the library (range-checkingon/off, function to call on fatal error, etc). Since these are accesseddirectly by the user it is obvious to the multi-threaded programmer thatthey 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 makeit impossible for someone to call a GSL routine from a multithreadedprogram.Legal issues
- Each contributor must make sure her code is under the GNU General PublicLicense (GPL). This means getting a disclaimer from your employer.
- We must clearly understand ownership of existing code and algorithms.
- Each contributor can retain ownership of their code, or sign it over toFSF as they prefer. There is a standard disclaimer in the GPL (take a look at it). The morespecific you make your disclaimer the more likely it is that it will beaccepted by an employer. For example,
- Obviously: don't use or translate non-free code. In particular don't copy or translate code from Numerical Recipesor ACM TOMS.Numerical Recipes is under a strict license and is not free software.The publishers Cambridge University Press claim copyright on all aspectsof the book and the code, including function names, variable names andordering of mathematical subexpressions. Routines in GSL should notrefer to Numerical Recipes or be based on it in any way. The ACM algorithms published in TOMS (Transactions on MathematicalSoftware) are not public domain, even though they are distributed on theinternet -- the ACM uses a special non-commercial license which is notcompatible with the GPL. The details of this license can be found on thecover page of ACM Transactions on Mathematical Software or on the ACMWebsite.Only use code which is explicitly under a free license: GPL or PublicDomain. If there is no license on the code then this does not mean itis public domain -- an explicit statement is required. If in doubt checkwith the author.
- I think one can reference algorithms from classic books onnumerical analysis (BJG: yes, provided the code is an independentimplementation and not copied from any existing software).
Non-UNIX portability
There is good reason to make this library work on non-UNIX systems. Itis probably safe to ignore DOS and only worry about windows95/windowsNTportability (so filenames can be long, I think).On the other hand, nobody should be forced to use non-UNIX systems fordevelopment.The best solution is probably to issue guidelines for portability, likesaying 'don't use XYZ unless you absolutely have to'. Then the Windowspeople will be able to do their porting.Compatibility with other libraries
We do not regard compatibility with other numerical libraries as apriority.However, other libraries, such as Numerical Recipes, are widely used.If somebody writes the code to allow drop-in replacement of theselibraries it would be useful to people. If it is done, it would be as aseparate wrapper that can be maintained and shipped separately.There is a separate issue of system libraries, such as BSD math libraryand functions likeexpm1
,log1p
,hypot
. Thefunctions in this library are available on nearly every platform (butnot all).In this case, it is best to write code in terms of these nativefunctions to take advantage of the vendor-supplied system library (forexample log1p is a machine instruction on the Intel x86). The libraryalso provides portable implementations e.g.gsl_hypot
which areused as an automatic fall back via autoconf when necessary. See theusage ofhypot
in 'gsl/complex/math.c', the implementationofgsl_hypot
and the corresponding parts of files'configure.in' and 'config.h.in' as an example.Parallelism
We don't intend to provide support for parallelism within the libraryitself. A parallel library would require a completely different designand would carry overhead that other applications do not need.Precision
For algorithms which use cutoffs or other precision-related terms pleaseexpress these in terms of GSL_DBL_EPSILON and GSL_DBL_MIN, or powers orcombinations of these. This makes it easier to port the routines todifferent precisions.Miscellaneous
Don't use the letterl
as a variable name -- it is difficult todistinguish from the number1
. (This seems to be a favorite inold Fortran programs).Final tip: one perfect routine is better than any number of routinescontaining errors.The subroutines and source code in the GNU Scientific Library package are 'free';this means that everyone is free to use them and free to redistributethem on a free basis. The GNU Scientific Library-related programs are not in thepublic domain; they are copyrighted and there are restrictions on theirdistribution, but these restrictions are designed to permit everythingthat a good cooperating citizen would want to do. What is not allowedis to try to prevent others from further sharing any version of theseprograms that they might get from you.Specifically, we want to make sure that you have the right to giveaway copies of the programs that relate to GNU Scientific Library, that you receivesource code or else can get it if you want it, that you can change theseprograms or use pieces of them in new free programs, and that you knowyou can do these things.To make sure that everyone has such rights, we have to forbid you todeprive anyone else of these rights. For example, if you distributecopies of the GNU Scientific Library-related code, you must give the recipients allthe rights that you have. You must make sure that they, too, receive orcan get the source code. And you must tell them their rights.Also, for our own protection, we must make certain that everyonefinds out that there is no warranty for the programs that relate toGNU Scientific Library. If these programs are modified by someone else and passedon, we want their recipients to know that what they have is not what wedistributed, so that any problems introduced by others will not reflecton our reputation.The precise conditions of the licenses for the programs currentlybeing distributed that relate to GNU Scientific Library are found in the GeneralPublic Licenses that accompany them.This document was generated using the texi2html translator version 1.54.