libftsh
A Fast Transform for Spherical Harmonics
 All Data Structures Files Functions Variables Defines
TEST/README

Copyright (c) 2000, 2012 Martin J. Mohlenkamp

This is the README file for libftsh/TEST. It has two purposes:

  1. To tell you how to do some simple tests that everything is working.
  2. To show by example how to use the ftsh library.

Tests:

After installing the library as instructed by ftsh/README, try the following commands in order:

make f1
./initialize_f1 192 191 1e-5 f1dat.bin
./random_coef 191 rcdat.bin
./synthesize_f1 f1dat.bin rcdat.bin s1dat.bin
./analyse_f1 f1dat.bin s1dat.bin a1dat.bin
./diff_coef 191 rcdat.bin a1dat.bin

If you had problems compiling or running, most likely something in libftsh/make.inc is improperly set. Next look at the final line, which should look like

> error 2.054069e-06 out of norm 1.000000e+00, relative error 2.054069e-06

The actual error may vary, but it should be less than 1e-5 Next look for the line:

> Wrote to file f1dat.bin . Compression ratio =  1.89

If you have a different ratio, something is not working.

Also run the following commands in order:

make d1
./initialize_d1 192 191 d1dat.bin
./random_coef 191 rcdat.bin
./synthesize_d1 d1dat.bin rcdat.bin sd1dat.bin
./analyse_d1 d1dat.bin sd1dat.bin ad1dat.bin
./diff_coef 191 rcdat.bin ad1dat.bin

The error should be slightly larger than your machine round-off error for the precision you are running.

Usage:

The transform has three parts, initialization, analysis, and synthesis. They appear in the files:

These files include documentation on the proper syntax, and should serve as models on how to use libftsh.

In the initialization stage, you tell what size problem you are doing and to what precision you need the answer, it does a slow computation on how to best do your problem, and saves its conclusions to a file. Not all sizes are allowed; see initialize_f1.c for details.

In the synthesis stage, you give transform coefficients and it produces function values, using the results of the initialization. The demo version does one synthesis (without the fourier transform in longitude) and outputs the results to file. In real life you will load in the results of the initialization and then do many syntheses and analyses (and other operations).

The analysis stage does the reverse of the synthesis stage.

The test that you ran above has two other programs:

Performance Testing:

Several routines are provided for rudimentary performace testing.

First, the "d1" series of routines implement the direct (ordinary matrix-vector multiplication) version of the transform. This can be used to compare run-times. (It can also be used to check correctness. If you use the same set of input coefficients, you can compare function values with diff_fcn.c .)

Second, the routines assess_f1 and assess_d1 do a more detailed analysis of the run times, by timing each order (m) separately.

The behavior you should expect is that the "fast" f1 synthesis (or analysis) breaks even with the direct d1 version around degree 128, and is three times faster at 512. Performance of the f1 version will also depend on the factorization of the degree.