Northern
Utah
WebSDR
|
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:
- Your SPECIFIC computer hardware - A "Wisdom" file is "custom" to your CPU and computer configuration (CPU type, instructions, speed, etc.) but this also means that it must be run on each and every system on which you install ka9q-radio as the optimizations of one may not be appropriate to another.
- The TYPE of FFT operation being done - KA9Q radio can input and output at least three types of data:
- "Real" input -
This type of data is the result of a fast, broadband A/D converter.
Converters of this type are found in many modern, direct-sampling
radios (e.g. Icom IC-7300) as well as in receivers such as the KiwiSDR, Red Pitaya and the RX-888.
- "Complex" input -
Many SDRs use frequency converters with quadrature local oscillators to
produce "I" and "Q" data. Such receivers include the Airspy,
RTL-SDR, SDRPlay and "SoftRock" types.
- "Complex" output - ka9q-radio produces "I//Q" outputs (although the end result of KA9Q radio will likely be the result of processing I/Q data to yield AM, FM, SSB, etc.) As the signal data internal to ka9q-radio is FFT data, an "Inverse" (or "backwards") FFT (also called "IFFT") is used to produce the desired signals at the intended bandwidth and sample rate.
- The sample rate - KA9Q radio can accept input
data from a few kHz to well over 100 MHz - and it is capable of
outputting signals with sample rates from kiloHertz to Megahertz.
- The "block time" - ka9q-radio processes data in "blocks" of discrete time intervals. The typical value for ka9q-radio is 20 milliseconds (50 Hz) but it may be configured as appropriate for the task and performance.
- The "overlap" - Every "block" of data processed by ka9q-radio contains some from the previous block of data to aid in its analysis in a time-continuous manner.
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:
- STOP
any CPU-intensive processes. If you are running ka9q-radio, a
WebSDR or something else, be sure to stop these to free as much CPU
time as practical.
- As the user under which ka9q-radio is running (e.g. radio)
go to /etc/fftw
- In that directory you will find the file "wisdomf" -
this is the current wisdom file. This should be copied as a
backup, e.g.: sudo cp wisdomf wisdomf-old .
- Leave the original "wisdomf" in place as it is
checked/used when creating new data: If the existing data
contains the needed optimization, it will be re-used, possibly saving
considerable time.
- Create a new temporary wisdom file: sudo touch nwisdom. Be sure that it has the necessary permissions to allow it to be written.
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:
- time - allows the duration of the FFTW3 wisdom
generation to be shown upon completion
- fftwf-wisdom - This is the program that actually
generates the wisdom file, producing the temporary file "nwisdom"
that we created. This program's usage includes the following arguments:
- -v Verbose output (e.g. on which parameter it's estimating)
- -T
Number of threads. In the example above, "-T 1" optimizes
for 1 CPU thread. Change this only if you know what you are doing.
- -o Send wisdom data to an output file rather than STDOUT - the file "nwisdom" is used in the above example
Additional parameters for "fftwf-wisdom":
- -m FFTW wisdom creation mode.
- By default this is "FFTW_PATIENT" which can take a bit of time, particularly for larger values.
- "FFTW_ESTIMATE" - This is a fast (cursory) analysis but it may not result in efficient operation.
- "FFTW_EXHAUSTIVE" - This is a very thorough analysis, but it can take many hours (even days!) to process large values.
- -n "No system wisdom". This prevents importation of "/etc/fftw/wisdomf" forcing a complete
recalculation of old data rather than attempting to re-use it. By
not reusing previously-calculated data the run time can be
significantly increased.
The arguments specifying the transformation sizes can have several several prefixes:
- rof - This indicates a forward FFT for real
data - that is non-I/Q data, such as that from
the rx-888 or other device that simply samples the RF.
- cof - This indicates a forward FFT
for complex data - that is I/Q data,
such as that from an Airspy, RTL-SDR, SDRPlay, a "Progrock"
device, etc.
- cob - This indicates a backwards
(e.g. "reverse" or "inverse" a.k.a. IFFT) to produce complex
data from already-processed FFT data from ka9q-radio - that is,
it's the complex output data.
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:
- blocktime = 20 This represents 20 milliseconds, or 0.02
seconds
- overlap = 5 This represents a 1/5th overlap between the
past and current block.
IMPORTANT NOTES:
- While this data may be explicitly defined in the
radiod@xxx.conf file, you may find this configuration
commented out, in which case you will find the default
parameters in /usr/local/share/ka9q-radio/presets.conf
. Refer to the "presets.conf" file to be certain
about the blocktime and overlap settings if they are not set explicitly in the "radio@xxx.conf" file!
- Remember: Larger numbers can take exponentially longer times to calculate, so it may take many hours for the process to complete with large numbers, particularly on slower processors.
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:
- "num" - The size of the transformation, preceded by "rof", "cof" and "cob" for ka9q-radio.
- "samplerate" - This is the sample rate specified for the input (source) or output data in samples-per-second.
- "blocktime" - This is the block time in seconds. In the example above, it is 0.02 seconds (e.g. 20 milliseconds).
- "overlap" - This is
the ratio of of overlap between the previous and current data. In
the example above, this is 5, meaning that 1/5th of the data is from
the previous block with the remaining 4/5 from the "current" data.
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 recent versions of ka9q-radio you may find suggested parameters to be used for wisdom creation in the file:
* * *
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:
-
rof3240000: RX888 MkII at 129.6
MHz real, 20 ms (50 Hz) block, overlap 5 (20%).
-
rof1620000: RX888 MkII at 64.8
MHz real, 20 ms (50 Hz) block, overlap 5 (20%).
-
rof500000: Airspy R2, 20 Ms/s
real, 20 ms (50 Hz) block time, overlap 5 (20%).
cof36480: Airspy HF+, 912 ks/s
complex, 20 ms (50 Hz), overlap 2 (20%).
-
cob1920 cob1200 cob960 cob800
cob600 cob480 cob320 cob300 cob200 cob160 cob150:
inverse FFTs for 20 ms (50 Hz) block times, overlap
factors of 2 and 5, and various common sample rates supported
by the
Opus codec (8/12/16/24/48 kHz).
- cob400: This is for 16 kHz bandwidth receive instances, 20 ms (50 Hz), ovverlap 2 (20%)
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:
- ls -l nwisdom wisdomf - check that nwisdom is larger
than wisdomf indicating that the new data has been added. If it
is not larger than the pre-existing "wisdomf" file, it
either failed in some way or it could not read the older file,
hence the warning above about keeping the original "wisdomf"
file in place.
- If you find that "nwisdom" is empty, that likely means that
"fftf-wisdom" terminated (or the system was restarted) prior
to its completion.
- cp -i nwisdom wisdomf - This will overwrite the old
wisdom file with the new one.
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:
- cd /etc/fftw - Go to directory with Wisdom data
- sudo touch nwisdom - Create a temporary file for the newly-generated Wisdom data
- STOP all other programs/processes
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:
- sudo time fftwf-wisdom -v -T 1 -o nwisdom rof1620000
rof500000 cof36480 cob1920 cob1200 cob960 cob800 cob600 cob480
cob400 cob320 cob300 cob200 cob160 cob150
If you are running an "standard"
ka9q-radio installation using RX-888 and you plan to use a sample rate of 129.6 MHz:
- sudo time fftwf-wisdom -v -T 1 -o nwisdom rof3240000
rof1620000 rof500000 cof36480 cob1920 cob1200 cob960 cob800 cob600 cob480
cob400 cob320 cob300 cob200 cob160 cob150
If you are running an "standard"
ka9q-radio installation using RX-888 at 64.8 MHz AND you wish to run a PA3FWM WebSDR:
- sudo time fftwf-wisdom -v -T 1 -o nwisdom rof3240000
rof1620000 rof500000 cof36480 cob1920 cob1200 cob960 cob800 cob600 cob480
cob400 cob320 cob300 cob200 cob160 cob150 cob2400 cob4800 cob9600
cob19200
If you are running an "standard"
ka9q-radio installation using an Airspy:
- sudo time fftwf-wisdom -v -T 1 -o nwisdom rof500000 cof36480 cob1920 cob1200 cob960 cob800 cob600 cob480
cob400 cob320 cob300 cob200 cob160 cob150
For other combinations, you'll need to read the page above and get out your calculator.
After the Wisdom file creation completes:
- ls -l nwisdom wisdomf
- This checks that nwisdom is larger
than wisdomf indicating that the new data has been added. If it
is not larger than the pre-existing "wisdomf" file, it
either failed in some way or it could not read the older file,
hence the warning above about keeping the original "wisdomf"
file in place.
- If you find that "nwisdom" is empty, that likely means that
"fftf-wisdom" terminated (or the system was restarted) prior
to its completion.
- cp -i nwisdom wisdomf
- This will overwrite the old
wisdom file with the new one.
For more information about ka9q-radio, go here:
This page has much more information about the internal workings of ka9q-radio and other examples of its use.
Additional
information:
- For general information about this WebSDR system -
including contact info - go to the about
page (link).
- For the latest news about this system and current issues,
visit the latest news
page (link).
- For more information about this server you may contact
Clint, KA7OEI using his callsign at ka7oei dot com.
- For more information about the WebSDR project in general -
including information about other WebSDR servers worldwide and
additional technical information - go to http://www.websdr.org
Back to the Northern Utah WebSDR
landing page