Northern
Utah
WebSDR

Nothern Utah WebSDR Logo - A skep with a Yagi 		Configuring FFTW3 the
"Wisdom" file -
And why you should pay attention to it!


 
"I just want to know how to run the damn Wisdom File generator!"

If you are of the tl;dr type, click HERE to jump to a very brief, concise set of instructions for a few common ka9q-radio configurations.
 


Why the Wisdom file is important:

The heart of KA9Q-Radio is the "FFTW3" algorithm - one that decomposes temporal data into the frequency and amplitude domain over time.  As this algorithm takes the majority of CPU cycles, it is VERY IMPORTANT that this be as efficient as possible.  If this algorithm is NOT optimized, it not only may consume an inordinate of CPU time, but it may produce bad data (e.g. choppy, missing data). 

Important:

This document represents an effort on my part to understand the operation of "ka9q-radio" and is not intended to be authoritative - see the ka9q-radio git for that!

As such, this is a work in progress and will certainly contain many "blank spots" and errors.  What it is intended to do is to help the new user along and start to get the "feel" of how the pieces go together.

Please read EVERY document in the /docs directory of the "ka9q-radio" git - and refer back when you see something you don't understand!



FFT optimization

As noted earlier, ka9q-radio makes extensive use of the FFTW3 algorithm for processing signals.  This algorithm is, by far, the most CPU-intensive portion of ka9q-radio and to reduce processor loading, it can be optimized for the current computing environment.  By default, ka9q-radio will perform a very cursory optimization (called "FFTW_ESTIMATE") to prevent a long start-up time, but if a significant portion of CPU time is being used by ka9q-radio, it's likely that it's not efficiently being used.   Significant performance gains may be had by doing a more thorough optimization (called "FFTW_PATIENT") which can dramaticly improve overall performance.  This optimization is computer-specific and should be done for each, individual installation of ka9q-radio and for EVERY sample rate that you plan to run.

A document describing the the task of FFT optimization is found in:  /ka9q-radio/docs/FFTW3.md (link).  Aspects of that file are included below for convenience but the reader should refer to that file as the authoritative source and read it, but the information below may be more informative to the causal user.
What is a "Wisdom" file, anyway?

The FFTW3 algorithm - being very computationally-intensive - can be optimized to be more efficient.  While this is not strictly necessary for it to "work", optimizing may be  necessary for some applications.  As mentioned earlier, because ka9q-radio is computer intensive - particularly at high sample rates - lack of optimization can mean that you may not have sufficient CPU time to handle all of the data - and since the signal processing being done is often time-critical, optimizing or not may make the difference between getting "good" data (free of drop-outs, holes, sequence issues) and not.

The "Wisdom" file is produced by another program - namely "fftwf-wisdom" that determines the optimization based on the following:
 What all of this means is that you should generate a "Wisdom" file that contains - at least - all of the sample rates that you plan to use - both input and output - for best performance.

Generating custom Wisdom files for ka9q-radio

While the steps in FFTW3.md will produce "Wisdom" data for

Here are the steps:

At this point, here a brief discussion on the types of "wisdom" data that will typically be encountered in ka9q-radio.  If you look at the suggested command line in FFTW3.md you will see the following line:

time fftwf-wisdom -v -T 1 -o nwisdom rof3240000 rof1620000 rof500000 cof36480 cob1920 cob1200 cob960 cob800 cob600 cob480 cob320 cob300 cob200 cob160 cob150

In the above command:

Additional parameters for "fftwf-wisdom":

The arguments specifying the transformation sizes can have several several prefixes:

Following the prefix is a number that is produced by knowing the sample rate, block time and overlap rate:  This data may be found in the radiod@xxx.conf file in which you define the operating parameters for the receive hardware in question.  Let us take an example of the RX-888:

Under the "[global]" section:

IMPORTANT NOTES:

It's worth noting that the typical block time and overlap are 20 msec (0.02) and 5, respectively.

Knowing the sample rate, block time and overlap, here is the formula that is used to calculate the number:

num = samplerate * blocktime * (overlap/(overlap-1)) - Where:

Taking an example of 64.8 MSPS from an RX-888, 20msec blocktime and an overlap of 5:

64800000 * 0.02 * 5/4 = 1620000

Since the RX-888 produces "real" data (not I/Q data) we would indicate type rof to produce a wisdom generation parameter of rof1620000 .

Now, let us say that you wanted to use ka9q-radio to produce 768 ksps of data for I/Q output.  Since the block time and overlap parameters are global, these, too, would be 20msec and 5, respectively, so we would have:

768000 * 0.02 * 5/4 = 192000

Because we are operating on the output from ka9q-radio - which uses "backwards" (inverse) FFT, we would use a wisdom generation parameter of cob19200

Comment:

* * *

In the file "FFTW3.md" Phil has a suggested line for generating the wisdom file:

time fftwf-wisdom -v -T 1 -o nwisdom rof3240000 rof1620000 rof500000 cof36480 cob1920 cob1200 cob960 cob800 cob600 cob480 cob320 cob300 cob200 cob160 cob150

Breaking this down:

If you operate any sample rate OTHER that those explicitly defined, above, you should create an entry in the command line specific to that application.  If you do NOT do this, the FFT and/or IFFT related to that specific rate.

For example, if we need output sample rates of 96, 192, 384 and 768 kHz, we would use the formula above and add to the line above:  cob2400 cob4800 cob9600 cob19200

As in:

time fftwf-wisdom -v -T 1 -o nwisdom rof3240000 rof1620000 rof500000 cof36480 cob1920 cob1200 cob960 cob800 cob600 cob480 cob320 cob300 cob200 cob160 cob150 cob2400 cob4800 cob9600 cob19200

Note:  You may need precede the above with "sudo" for it to work.

REMEMBER:  This process may take hours to complete so it might be a good idea to run it in tmux or precede the above line (after "sudo") with "nohup" so that it can continue working even if the ssh session terminates.  The output text (which may be in "nohup.out" if you ran it that way) will indicate how long it took to produce the wisdom data.

Once the line above has completed do:

At this point, restart ka9q-radio for these parameters to take effect.


The tl:dr part - common ka9q-radio configurations:

This section gives a very brief set of instructions on generating the Wisdom file.  Please note that these may take HOURS to complete!

For ALL implementions:
 If you are running an "standard" ka9q-radio installation using  RX-888 at 64.8 MHz but you are NOT every going to operate at 129.6 MHz sample rate:
If you are running an "standard" ka9q-radio installation using  RX-888 and you plan to use a sample rate of 129.6 MHz:
 If you are running an "standard" ka9q-radio installation using  RX-888 at 64.8 MHz AND you wish to run a PA3FWM WebSDR:
 If you are running an "standard" ka9q-radio installation using an Airspy:
For other combinations, you'll need to read the page above and get out your calculator.

After the Wisdom file creation completes:


For more information about ka9q-radio, go here:
Using KA9Q-Radio - link

This page has much more information about the internal workings of ka9q-radio and other examples of its use.

Additional information:
 Back to the Northern Utah WebSDR landing page