Merge branch 'master' into bind-dev

.gitignore

@@ -8,6 +8,7 @@
 *.gcno
 *.o
 *.so
+*~
 
 # ignore swap files for vim editing
 *.swp
@@ -30,6 +31,9 @@ config.status
 makefile
 xautotest
 *.m
+autotest.json
+autotest/logs/*.bin
+autotest/logs/*.gnu
 
 # miscellany
 octave-core

HISTORY

@@ -1,6 +1,106 @@
 
 ## Latest improvements ##
 
+## Improvements for v1.6.0 ##
+
+Version 1.6.0 includes a new qdsync object to greatly simplify the frame
+synchronization process in liquid, allowing for both detection and channel
+impairment correction with a simplified interface. Additionally, code
+coverage has been increased to 85% across the entire project, with numerous
+bug fixes, stability improvements, and massive testing enhancements. From
+an "architectural" standpoint, objects have been migrated to use standard
+methods for consistency.
+
+  * build
+    - increased code coverage to 85% globally across entire project. This
+      is the single largest effort included in this version and touches
+      most modules in some way, most particularly the framing objects
+    - cleaning build to remove compiler warnings (e.g. unused variables)
+    - stripped version number off archive
+  * dotprod
+    - added support for AVX512-F (thanks, @vankxr!)
+  * framing
+    - added numerous tests to increase coverage to 84%
+    - framesync64: using new qdsync object for simplified operation
+    - qdsync: new frame detector and synchronizer to much more easily
+      support frame processing. The object not only detects the frame, but
+      also provides an initial carrier frequency, phase, and timign offset,
+      and also corrects for these impairments, passing the results to the
+      user in a clean callback function.
+  * modem
+    - cpfskmod: increasing phase stability for long runs
+  * multichannel
+    - added numerous tests to increase coverage to 88%
+  * optim
+    - added numerous tests to increase coverage to 92%
+  * sequence
+    - msequence: extended support for state variables up to m=31, reversed
+      order for generator polynomial and internal state definition to be
+      more consistent with literature and readily-available genpolys
+
+## Improvements for v1.5.0 ##
+
+This release includes substantially improved testing coverage, deep copy()
+methods for nearly all objects, improved speed, and resolves a number of
+issues and pull requests.
+
+  * build
+    - added support for PlatformIO (https://platformio.org) for embeedded
+      development (thanks, @jcw!)
+    - incorporated recursive copy() methods to objects to facilitate c++ copy
+      constructors for bindings; now all objects can be deep copied to a new
+      object with their entire memory and state preserved
+    - added convenience method to malloc and copy memory arrays
+    - improved support for error codes across objects and methods
+    - cleaned up spelling errors across project (thanks, @nowls!)
+    - scrubbed function argument variable names to avoid underscore followed
+      by a capital letter, causing trouble with pre-compiler processing
+    - added basic test to check linking to installed library, incorporating
+      into CI/CD pipelines
+    - added more example programs
+  * autotest
+    - increased coverage testing (81% across entire project)
+    - added the ability to "hammer" a particular test by running repeatedly on
+      incremental seeds to assess specific edge cases (e.g. with random data)
+    - added timer to show execution time for each test and identify areas for
+      speed improvements
+    - added methods for testing spectral response of various fields
+    - added special directory for storing output logs: autotest/logs/
+  * benchmark
+    - replacing old C-based benchmark comparison with simpler python version
+  * dotprod
+    - added support for AVX SIMD in vector dot products (thanks, @vankxr!)
+  * fft
+    - adding macro to allow for aligned memory allocation if FFTW is used
+      (thanks, @nowls!)
+  * filter
+    - added new halfband filter design using Parks-McClellan algorithm and
+      qs1dsearch method to provide as exact a specification as possible
+    - added method to retrieve filter response from coefficients array
+    - dds: adding methods to get/set scale
+    - firhilb, iirhilb: added block processing method
+    - msresamp, resamp: adding method to provide the exact number of output
+      samples with provided input size
+    - msresamp2, resamp2: using better halfband filter design for exact user
+      specifications
+    - resamp: adding methods to get/set scale, fixing filter bank resolution
+      (was hard-coded, now respects user configuration)
+  * framing
+    - framesync64: added methods to set callback and userdata (context)
+      fields, adding support for exporting debugging files for post-analysis
+      as well as python script for processing, adding better estimate of
+      error vector magnitude
+    - msource: added convenience method to recall number of samples generated
+      by each source
+    - ofdmflexframesync: added methods to set callback and userdata (context)
+      fields
+    - qpacketmodem: returning much better estimate of error vector magnitude
+    - qsource: fixed issue with carrier frequency adjustment
+  * optim
+    - added qs1dsearch object to perform quad-section 1-dimensional search:
+      similar to bisection search, but to find potentially non-continuous
+      minimum/maximum of function
+
 ## Improvements for v1.4.0 ##
 
   * autotest

README.md

@@ -296,11 +296,36 @@ lib_deps = https://github.com/jgaeddert/liquid-dsp.git
 ### License ###
 
 liquid projects are released under the X11/MIT license.
+By default, this project will try to link to [FFTW](http://www.fftw.org) if it
+is available on your build platform.
+Because FFTW starting with version 1.3 is
+[licensed](http://www.fftw.org/faq/section1.html)
+under the [GNU General Public License v2](http://www.fftw.org/doc/License-and-Copyright.html)
+this unfortunately means that (and I'm clearly not a lawyer, here)
+you cannot distribute `liquid-dsp` without also distributing the source code
+if you link to FFTW.
+This is a similar situation with the classic
+[libfec](https://github.com/quiet/libfec)
+which uses the
+[GNU Lesser GPL](https://www.gnu.org/licenses/licenses.html#LGPL).
+Finally, `liquid-dsp` makes extensive use of GNU
+[autoconf](https://www.gnu.org/software/autoconf/),
+[automake](https://www.gnu.org/software/automake/),
+and related tools.
+These are fantastic libraires with amazing functionality and their authors
+should be lauded for their efforts.
+In a similar vain, much the software I write for a living I give away for
+free;
+however I believe in more permissive licenses to allow individuals the
+flexibility to use software with fewer limitations.
+If these restrictions are not acceptible, `liquid-dsp` can be compiled and run
+without use of these external libraries, albeit a bit slower and with limited
+functionality.
+
 Short version: this code is copyrighted to me (Joseph D. Gaeddert),
 I give you full permission to do whatever you want with it except remove my
 name from the credits.
-Seriously, go nuts.
-See the LICENSE file or
-[https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT)
-for specific terms.
+Seriously, go nuts! but take caution when linking to other libraries with
+different licenses.
+See the [license](https://opensource.org/licenses/MIT) for specific terms.
 

configure.ac

@@ -1,4 +1,4 @@
-# Copyright (c) 2007 - 2022 Joseph Gaeddert
+# Copyright (c) 2007 - 2023 Joseph Gaeddert
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -23,7 +23,7 @@
 # Process with autoconf to generate configure script
 #
 
-AC_INIT([liquid-dsp],[1.4],[joseph@liquidsdr.org])
+AC_INIT([liquid-dsp],[1.6],[joseph@liquidsdr.org])
 AC_CONFIG_SRCDIR([src/libliquid.c])
 AC_CONFIG_MACRO_DIR([scripts])
 
@@ -170,9 +170,18 @@ else
         #   SSSE3   :   tmmintrin.h
         #   SSE4.1/2:   smmintrin.h
         #   AVX     :   immintrin.h
+        #   AVX2    :   immintrin.h
+        #   AVX512  :   immintrin.h
         AX_EXT
 
-        if [ test "$ax_cv_have_avx2_ext" = yes ]; then
+        if [ test "$ax_cv_have_avx512f_ext" = yes ]; then
+            # AVX512 extensions
+            MLIBS_DOTPROD="src/dotprod/src/dotprod_cccf.avx512f.o \
+                           src/dotprod/src/dotprod_crcf.avx512f.o \
+                           src/dotprod/src/dotprod_rrrf.avx512f.o \
+                           src/dotprod/src/sumsq.avx512f.o"
+            ARCH_OPTION='-mavx512f'
+        elif [ test "$ax_cv_have_avx2_ext" = yes ]; then
             # AVX2 extensions
             MLIBS_DOTPROD="src/dotprod/src/dotprod_cccf.avx.o \
                            src/dotprod/src/dotprod_crcf.avx.o \
@@ -188,24 +197,24 @@ else
             ARCH_OPTION='-mavx'
         elif [ test "$ax_cv_have_sse41_ext" = yes ]; then
             # SSE4.1/2 extensions
-            MLIBS_DOTPROD="src/dotprod/src/dotprod_cccf.mmx.o \
-                           src/dotprod/src/dotprod_crcf.mmx.o \
-                           src/dotprod/src/dotprod_rrrf.sse4.o \
-                           src/dotprod/src/sumsq.mmx.o"
+            MLIBS_DOTPROD="src/dotprod/src/dotprod_cccf.sse.o \
+                           src/dotprod/src/dotprod_crcf.sse.o \
+                           src/dotprod/src/dotprod_rrrf.sse.o \
+                           src/dotprod/src/sumsq.sse.o"
             ARCH_OPTION='-msse4.1'
         elif [ test "$ax_cv_have_sse3_ext" = yes ]; then
             # SSE3 extensions
-            MLIBS_DOTPROD="src/dotprod/src/dotprod_cccf.mmx.o \
-                           src/dotprod/src/dotprod_crcf.mmx.o \
-                           src/dotprod/src/dotprod_rrrf.mmx.o \
-                           src/dotprod/src/sumsq.mmx.o"
+            MLIBS_DOTPROD="src/dotprod/src/dotprod_cccf.sse.o \
+                           src/dotprod/src/dotprod_crcf.sse.o \
+                           src/dotprod/src/dotprod_rrrf.sse.o \
+                           src/dotprod/src/sumsq.sse.o"
             ARCH_OPTION='-msse3'
         elif [ test "$ax_cv_have_sse2_ext" = yes ]; then
             # SSE2 extensions
-            MLIBS_DOTPROD="src/dotprod/src/dotprod_cccf.mmx.o \
-                           src/dotprod/src/dotprod_crcf.mmx.o \
-                           src/dotprod/src/dotprod_rrrf.mmx.o \
-                           src/dotprod/src/sumsq.mmx.o"
+            MLIBS_DOTPROD="src/dotprod/src/dotprod_cccf.sse.o \
+                           src/dotprod/src/dotprod_crcf.sse.o \
+                           src/dotprod/src/dotprod_rrrf.sse.o \
+                           src/dotprod/src/sumsq.sse.o"
             ARCH_OPTION='-msse2'
         else
             # portable C version

examples/framesync64_performance_example.c

@@ -10,10 +10,11 @@
 // add noise to channel
 void frame64_add_noise(float complex * _buf, float _SNRdB)
 {
-    float nstd = powf(10.0f, -_SNRdB/20.0f) * M_SQRT1_2;
+    float nstd = powf(10.0f, -_SNRdB/20.0f);
+    nstd *= M_SQRT2; // scale noise to account for signal being over-sampled by 2
     unsigned int i;
     for (i=0; i<LIQUID_FRAME64_LEN; i++)
-        _buf[i] += nstd*( randnf() + _Complex_I*randnf() );
+        _buf[i] += nstd*( randnf() + _Complex_I*randnf() ) * M_SQRT1_2;
 }
 
 int main(int argc, char*argv[])
@@ -24,15 +25,18 @@ int main(int argc, char*argv[])
     unsigned int min_errors =   50;
     unsigned int min_trials =  500;
     unsigned int max_trials = 5000;
+    float per_target = 1e-2f;
 
     // create buffer for the frame samples
     float complex frame[LIQUID_FRAME64_LEN];
-    float SNRdB = -6.0f;
+    float SNRdB = -3.0f;
+    float per_0 =-1.0f, per_1 = -1.0f;
+    float snr_0 = 0.0f, snr_1 =  0.0f;
     FILE* fid = fopen(OUTPUT_FILENAME, "w");
     fprintf(fid,"%% %s: auto-generated file\n", OUTPUT_FILENAME);
     fprintf(fid,"clear all; close all;\n");
     fprintf(fid,"SNR=[]; pdetect=[]; pvalid=[];\n");
-    printf("# %8s %6s %6s %6s\n", "SNR", "detect", "valid", "trials");
+    printf("# %8s %6s %6s %6s %12s\n", "SNR", "detect", "valid", "trials", "PER");
     while (SNRdB < 10.0f) {
         framesync64_reset_framedatastats(fs);
         unsigned int num_trials = 0, num_errors = 0;
@@ -60,8 +64,11 @@ int main(int argc, char*argv[])
         }
         // print results
         framedatastats_s stats = framesync64_get_framedatastats(fs);
-        printf("  %8.3f %6u %6u %6u\n",
-            SNRdB,stats.num_frames_detected,stats.num_payloads_valid,num_trials);
+        float per = (float)(num_trials - stats.num_payloads_valid)/(float)num_trials;
+        if      (per >= per_target) { per_0 = per; snr_0 = SNRdB; }
+        else if (per_1 < 0.0f     ) { per_1 = per; snr_1 = SNRdB; }
+        printf("  %8.3f %6u %6u %6u %12.4e\n",
+            SNRdB,stats.num_frames_detected,stats.num_payloads_valid,num_trials,per);
         fprintf(fid,"SNR(end+1)=%g; pdetect(end+1)=%g; pvalid(end+1)=%g;\n",
                 SNRdB,
                 (float)stats.num_frames_detected / (float)num_trials,
@@ -70,6 +77,10 @@ int main(int argc, char*argv[])
             break;
         SNRdB += 0.5f;
     }
+    float m = (logf(per_1) - logf(per_0)) / (snr_1 - snr_0);
+    float snr_target = snr_0 + (logf(per_target) - logf(per_0)) / m;
+    printf("per:{%12.4e,%12.4e}, snr:{%5.2f,%5.2f} => %.3f dB for PER %12.4e\n",
+            per_0, per_1, snr_0, snr_1, snr_target, per_target);
     fprintf(fid,"figure;\n");
     fprintf(fid,"hold on;\n");
     fprintf(fid,"  semilogy(SNR, 1-pdetect+eps,'-o', 'LineWidth',2, 'MarkerSize',2);\n");
@@ -88,3 +99,4 @@ int main(int argc, char*argv[])
     framesync64_destroy(fs);
     return 0;
 }
+

examples/fskframesync_example.c

@@ -1,13 +1,8 @@
-//
-// fskframesync_example.c
-//
 // This example demonstrates the interfaces to the fskframegen and
 // fskframesync objects used to completely encapsulate data for
 // over-the-air transmission.
 //
 // SEE ALSO: flexframesync_example.c
-//
-
 #include <stdio.h>
 #include <stdlib.h>
 #include <math.h>