pywigner 1.12

Wigner Symbols

This is only a test to provide support for a pyproject.toml file! The original project can be found here. This repository will be deleted when the changes have been submitted to the authors!

TOC

• TOC
• 1. Purpose
• 2. License
• 3. Compilation
• 4. Command-line evaluation of single symbols
• 5. Library interfaces
  • 5.1 Simple C interface
  • 5.2 Simple FORTRAN interface
  • 5.3 Python-interface
  • 5.4 Native interface
• 6. Acknowledgements (referencing)
• 7. Contact

1. Purpose

WIGXJPF evaluates Wigner 3j, 6j and 9j symbols accurately using prime factorisation and multi-word integer arithmetic.

2. License

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

WIGXJPF 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 WIGXJPF. 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 (< 1 s runtime) can be performed by:

make test

Some large and huge symbols can also be tested, but they require more time and memory (~30 s, 30 MiB and ~25 min, 30.2 GiB, respectively):

make test-large
make test-huge

The C functions can also be directly used from C++, to test:

make ccsimple.test

The fortran interface is pure C code and compiled with the library above. Testing it requires a fortran compiler, e.g. gfortran:

make fsimple.test FC=gfortran

The basic functions of the library are as such thread-safe, see below for details. openMP is required to check threaded operation with the simple C interface:

make cthreadedsimple.test

The python interface requires numpy and cffi, and can be tested:

make pysimple.test
make pysimple2.test   # For explicit python2
make pysimple3.test   # For explicit python3

4. Command-line evaluation of single symbols

Individual symbols can be evaluated directly from the command line by the bin/wigxjpf program. Half-integer arguments are given as .5. Examples:

bin/wigxjpf --3j=1.5,1.5,1,1.5,-0.5,-1

bin/wigxjpf --6j=2,2,1,2,1,1

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

5. Library interfaces

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

1. Setup of precalculated table of prime-factorised factorials. The table must be large enough to handle the largest symbol that shall be evaluated. For multi-threaded programs, this is done once (globally). The limit max_two_j is chosen as the largest two_j in any symbol calculated, and wigner_type as the (largest of) 3, 6, or 9 for 3j, 6j, or 9j symbols respectively. Only one table is used even if different symbols are evaluated. Note that giving e.g. max_two_j = 2*100 and wigner_type = 9 only requires < 400 kB of memory, such that there is nowadays little point in keeping this limit very tight. The evaluation routines will only use the necessary parts of each prime-factorisation list, so there is only a slight cache penalty for using larger tables than necessary.

2. Allocation of temporary storage for the evaluation routines. Enough space must be allocated for the largest symbol that shall be evaluated. It also depends on the tables above, which must be allocated first. As above, there is little to gain by giving this limit tightly, giving e.g. max_two_j = 2*100 uses less than 50 kB. For multi-threaded programs, this must be done once per thread.

3. Evaluate symbols. Repeat...

4. Free above temporary and table memory.

Interfaces:

• Simple C interface. This is recommended.
• Simple FORTRAN interface.
• Native interface. This gives access to long double and quad double (__float128) results.
• Python interface.

Independent of interface, error handling is brutal: if a symbol that exceeds the tables or temporary storage is evaluated, the library will print an error message and terminate the program.

5.1 Simple C interface

See function prototypes in inc/wigxjpf.h (upper part).

1. #include "wigxjpf.h"

2. void wig_table_init(int max_two_j, int wigner_type);

3. void wig_temp_init(int max_two_j); /* Single-threaded / void wig_thread_temp_init(int max_two_j); / Multi-threaded. */

   When the program is multi-threaded, this routine must be called by each thread that will evaluate symbols. The pointer to the temporary array is kept as a thread-specific global variable.

   wig_temp_init() and wig_thread_temp_init() do exactly the same thing. By using wig_thread_temp_init(), it is ensured that the WIGXJPF library was compiled with the temporary storage array as a thread-specific variable.

4. double wig3jj(int two_j1, int two_j2, int two_j3, int two_m1, int two_m2, int two_m3);

   And similar for 6j and 9j symbols.

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

5. void wig_temp_free(); /* Per-thread when multi-threaded. */ void wig_table_free();

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

To compile and link with WIGXJPF:

CFLAGS += -Ipath-to-wigxjpf/inc/
LDFLAGS += -Lpath-to-wigxjpf/lib/
LDLIBS += -lwigxjpf -lm

5.2 Simple FORTRAN interface

The FORTRAN interface is analog to the C interface described above. A 'f' is prepended to each function name. All arguments are of type 'integer4' and return values of type 'real8'.

A small example program can be found in example/fsimple.f.

The interface specifications are in a module fwigxjpf, which is placed in the mod/ directory during compilation of the FORTRAN test program (which also selects the FORTRAN compiler to use). Compilation of FORTRAN programs thus need to include also that directory:

FCFLAGS += -I path-to-wigxjpf/mod/

5.3 Python-interface

The python interface is analog to the C interface described above.

A module 'pywigxjpf' is available in pywigxjpf/pywigxjpf.py

The use of the module requires numpy and cffi.

To build the wrapper (required once):

make pywigxjpf_ffi

A small example program can be found in example/pysimple.py. As shown in this example, to use the interface in python, the module must be imported with, e.g.,

import pywigxjpf as wig

after which a number of functions (such as wig.wig3jj) become available. Help text is available via e.g.

help(wig)                # For interfaces.
help(wig.pywigxjpf)      # For usage information.

To find the module, the path can be set in PYTHONPATH, e.g. with bash:

export PYTHONPATH=path-to-wigxjpf/pywigxjpf/example/pysimple.py

Alternatively, the module can be installed (first build WIGXJPF):

make
python setup.py install

You may need to add --user to the second command.

Note: When evaluating a fair amount of symbols in python, it may be useful to try the numba jit compiler. See example/py_numba_example.py

5.4 Native interface

Use of the native interface follows the same structure as the simple interface. For function prototypes, see inc/wigxjpf.h (lower part).

Differences are:

• The initialisation routines are given the maximum factorial and number of iterations explicitly, and not as max_two_j. See wigxjpf.h for notes on how to calculate these from max_two_j.

• The temporary storage allocation returns a pointer to a structure, which must be sent explicitly to the evaluation routines. If running multi-threaded, the same pointer must not be used by several evaluations simultaneously.

• The result of evaluations are returned in locations given as argument pointers, not return values.

• The evaluation routines are named by the type they return (double, long double or float128). Since __float128 requires additional system libraries, their headers and functions have been separated out, to use them, additionally

  # include "wigxjpf_quadmath.h"

  and additionally link with

  LDLIBS += -lwigxjpf_quadmath -quadmath

• Even though explicit routines to check for trivial zeros of symbols are exposed, there is no need to call them unless only that result is required. They are always consulted by the evaluation routines.

6. Acknowledgements (referencing)

The recommended way to refer to WIGXJPF, when used for computations that are published in a research article, is to cite the following paper

H. T. Johansson and C. Forssén, Fast and Accurate Evaluation of Wigner 3j, 6j, and 9j Symbols Using Prime Factorization and Multiword Integer Arithmetic, SIAM J. Sci. Comput., 38(1) (2016), A376-A384.

@article{johansson2016,
   author = {H. T. Johansson and C. Forss\’en},
    title = {Fast and Accurate Evaluation of Wigner 3\$j\$, 6\$j\$, and 9\$j\$ Symbols Using Prime Factorization and Multiword Integer Arithmetic},
  journal = {SIAM Journal on Scientific Computing},
   volume = {38},
   number = {1},
    pages = {A376-A384},
     year = {2016},
      doi = {10.1137/15M1021908},
      URL = {http://dx.doi.org/10.1137/15M1021908},
   eprint = {http://dx.doi.org/10.1137/15M1021908}
}

Pre-print (2015) at arXiv:1504.08329.

7. Contact

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

Christian Forssén e-mail: [e-mail] Nuclear theory and few-body physics Department of Fundamental physics Chalmers University of Technology 412 96 Göteborg Sweden