Contents
========

1. Purpose
2. License
3. Compilation
4. Command-line evaluation of single symbols
5. Library interfaces
5a. Simple C interface
6. Acknowledgements (referencing)
7. Early-release software
8. Contact


1. Purpose
==========

WIGSGLL evaluates sequences of Wigner 3j, 6j and 9j symbols accurately 
using the Luscombe-Luban [1] improvements of the Schulten-Gordon schemes 
[2].

By performing the calculations with integers as far as possible, and
then with extended precision floating point (long double (80 bits with
x87 FPU on x86) or quad double (128 bits)), the evaluation is fast and
deliver full double precision results for small j (< 10 for long
double and presumably < 10000 for quad double).


2. License
==========

WIGSGLL is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

WIGSGLL is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with WIGSGLL.  If not, see <http://www.gnu.org/licenses/>.

For details, see the files COPYING.LESSER and COPYING.


3. Compilation
==============

All necessary configuration is performed during build.  The library is
compiled by issuing:

make

Test evaluation of some small symbols (few s runtime) can be performed
by:

make test

If WIGXJPF is available in a sibling directory:

make test-wigxjpf

The basic functions of the library are as such thread-safe, as there
are no global variables.


4. Command-line evaluation of single symbols
============================================

Individual strings of symbols can be evaluated directly from the
command line by the bin/wigsgll program.  Half-integer arguments are
given as .5.  For 3j or 6j symbols, either the first j or m is
replaced with an x.

Examples:

bin/wigsgll --3j=x,1.5,1,1.5,-0.5,-1

bin/wigsgll --3j=1.5,1.5,1,1.5,x,y

bin/wigsgll --6j=x,2,1,2,1,1

bin/wigsgll --9j=20,20,40,20,20,40,20,20,40


5. Library interfaces
=====================

WIGSGLL can be used as a library within other programs.  Several
interfaces are provided and described below.  They all follow the same
scheme:

1) Evaluate symbols.
   Repeat...

Interfaces:

- Simple C interface.

Independent of interface, error handling is brutal: if a string of
symbols is requested that has more entries then the supplied result
array, the library will print an error message and terminate the
program.


5a. Simple C interface
======================

See function prototypes in inc/wigsgll.h.

0) #include "wigsgll.h"

1) int wig3jjqdjd(/*   x   */ int two_j2, int two_j3,
                  /* -m2-m3*/ int two_m2, int two_m3,
                  double *res, size_t entries,
                  int *two_j1_min, int *two_j1_max);

   The call above evaluates a string of 3j symbols, for all j1 allowed
   by the other argument.  The result is stored in the array pointed
   to by res, with entries members.  If non-NULL, then the limits of
   j1 are reported in two_j1_min and two_j1_max.

   And similar for 3j-m 6j-j and 9j symbols.

   Note that the arguments are to be given as integers, with twice the
   numeric value (this is what jj in the function name tries to
   indicate).  I.e. half-integer arguments will be passed as odd
   integers.

A small example program can be found in example/csimple.c.

To compile and link with WIGSGLL:

CFLAGS += -Ipath-to-wigsgll/inc/
LDFLAGS += -Lpath-to-wigsgll/lib/
LDLIBS += -lwigsgll -lm


6. Acknowledgements (referencing)
=================================

The library implements routines based on the following articles:

[1] J. Luscombe and M. Luban,
    Simplified recursive algorithm for Wigner 3j and 6j symbols,
    Phys. Rev. E, 57 (1998), pp. 7274-7277.

[2] K. Schulten and R. G. Gordon,
    Exact recursive evaluation of 3j- and 6j-coefficients for
    quantum-mechanical coupling of angular momenta,
    J. Math. Phys, 16 (1975), pp. 1961-1970.


7. Early-release software
=========================

Please note that WIGSGLL has been written out of curiosity and has not
been used in any other program by the author.

The build tests do however compare it rather extensively against
WIGXJPF for smaller j.

If you use it in a project (successfully, and also when less so - for
improvements), the author would be grateful for any feedback or other
information!


8. Contact
==========

Håkan T. Johansson                  e-mail: f96hajo@chalmers.se
Subatomic physics
Department of Fundamental physics
Chalmers University of Technology
412 96 Göteborg
Sweden