File: whitening_processor.h

package info (click to toggle)
js8call 2.5.2%2Bds-1
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid
  • size: 24,720 kB
  • sloc: cpp: 562,651; sh: 898; python: 132; ansic: 102; makefile: 4
file content (259 lines) | stat: -rw-r--r-- 9,129 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
#pragma once

#include <algorithm>
#include <array>
#include <cmath>
#include <cstdlib>
#include <numeric>
#include <optional>
#include <sstream>
#include <vector>

#include <QDebug>
#include <QLoggingCategory>

Q_DECLARE_LOGGING_CATEGORY(decoder_js8);

namespace js8 {
/**
 * @brief Compute per-tone/symbol noise medians and whiten LLRs for a JS8 frame.
 *
 * Given symbol magnitudes (sans Costas) and winners, produces normalized
 * LLR0/LLR1, optionally applying noise-based whitening and erasure. Fully
 * templated on matrix dimensions, so it stays header-only; used inside the JS8
 * decoder per candidate.
 */
template <int NROWS, int ND, int N> class WhiteningProcessor {
  public:
    struct Result {
        std::array<float, 3 * ND> llr0;
        std::array<float, 3 * ND> llr1;
        bool whiteningApplied;
        bool erasureApplied;
        std::size_t erasures;
        double avgAbsPre;
        double avgAbsPost;
    };

    static Result process(std::array<std::array<float, ND>, NROWS> const &s1,
                          std::array<int, ND> const &symbolWinners,
                          float erasureThreshold, bool debug) {
        auto const median =
            [](std::vector<float> &values) -> std::optional<float> {
            if (values.empty())
                return std::nullopt;

            auto const mid = values.size() / 2;

            std::nth_element(values.begin(), values.begin() + mid,
                             values.end());
            float med = values[mid];

            if ((values.size() % 2) == 0 && mid > 0) {
                std::nth_element(values.begin(), values.begin() + (mid - 1),
                                 values.end());
                med = 0.5f * (med + values[mid - 1]);
            }

            return med;
        };

        // Estimate per-tone noise using non-winning tone magnitudes across the
        // frame.
        auto const toneNoise =
            [&]() -> std::optional<std::array<float, NROWS>> {
            std::array<std::vector<float>, NROWS> toneSamples;
            std::array<float, NROWS> noise = {};

            // Collect non-winning magnitudes for each tone.
            for (int j = 0; j < ND; ++j) {
                int const winner = symbolWinners[j];

                for (int i = 0; i < NROWS; ++i) {
                    if (i != winner)
                        toneSamples[i].push_back(s1[i][j]);
                }
            }

            bool ok = true;

            for (int i = 0; i < NROWS; ++i) {
                if (auto m = median(toneSamples[i]); m) {
                    noise[i] = *m;
                } else {
                    ok = false;
                    break;
                }
            }

            if (!ok)
                return std::nullopt;

            return noise;
        }();

        if (toneNoise && debug) {
            std::ostringstream oss;

            oss << "toneNoise:";
            for (auto const value : *toneNoise)
                oss << ' ' << value;

            qCDebug(decoder_js8).noquote() << oss.str().c_str();
        }

        // Estimate per-symbol noise using non-winning tone magnitudes per
        // symbol.
        auto const symbolNoise = [&]() -> std::optional<std::vector<float>> {
            std::vector<float> noise;
            noise.reserve(ND);

            for (int j = 0; j < ND; ++j) {
                std::vector<float> bins;
                bins.reserve(NROWS - 1);

                int const winner = symbolWinners[j];

                for (int i = 0; i < NROWS; ++i) {
                    if (i != winner)
                        bins.push_back(s1[i][j]);
                }

                if (auto m = median(bins); m) {
                    noise.push_back(*m);
                } else {
                    return std::nullopt;
                }
            }

            return noise;
        }();

        if (symbolNoise && !symbolNoise->empty() && debug) {
            auto const [minIt, maxIt] =
                std::minmax_element(symbolNoise->begin(), symbolNoise->end());
            float const avg = std::accumulate(symbolNoise->begin(),
                                              symbolNoise->end(), 0.0f) /
                              static_cast<float>(symbolNoise->size());

            qCDebug(decoder_js8)
                << "symbolNoise avg/min/max" << avg << *minIt << *maxIt;
        }

        Result result{};

        bool const disableWhitening =
            std::getenv("JS8_DISABLE_WHITENING") != nullptr;
        bool const whiteningAvailable = toneNoise && symbolNoise &&
                                        !symbolNoise->empty() &&
                                        !disableWhitening;
        bool const applyErasureInWhitening =
            whiteningAvailable && erasureThreshold > 0.0f;
        double sumAbsPre = 0.0;
        double sumAbsPost = 0.0;
        std::size_t erasures = 0;

        for (int j = 0; j < ND; ++j) {
            int const i1 = 3 * j;     // First column (matches Fortran's i1)
            int const i2 = 3 * j + 1; // Second column (matches Fortran's i2)
            int const i4 = 3 * j + 2; // Third column (matches Fortran's i4)

            std::array<float, NROWS> ps;

            for (int i = 0; i < NROWS; ++i)
                ps[i] = s1[i][j];

            // Assign to `bmeta` in column order, with correct values
            result.llr0[i1] = std::max({ps[4], ps[5], ps[6], ps[7]}) -
                              std::max({ps[0], ps[1], ps[2], ps[3]}); // r4
            result.llr0[i2] = std::max({ps[2], ps[3], ps[6], ps[7]}) -
                              std::max({ps[0], ps[1], ps[4], ps[5]}); // r2
            result.llr0[i4] = std::max({ps[1], ps[3], ps[5], ps[7]}) -
                              std::max({ps[0], ps[2], ps[4], ps[6]}); // r1

            for (auto &x : ps)
                x = std::log(x + 1e-32f);

            // Assign to `bmetb` in column order, with correct values
            result.llr1[i1] = std::max({ps[4], ps[5], ps[6], ps[7]}) -
                              std::max({ps[0], ps[1], ps[2], ps[3]}); // r4
            result.llr1[i2] = std::max({ps[2], ps[3], ps[6], ps[7]}) -
                              std::max({ps[0], ps[1], ps[4], ps[5]}); // r2
            result.llr1[i4] = std::max({ps[1], ps[3], ps[5], ps[7]}) -
                              std::max({ps[0], ps[2], ps[4], ps[6]}); // r1

            if (whiteningAvailable) {
                int const winner = symbolWinners[j];
                float const tn = std::max(0.0f, (*toneNoise)[winner]);
                float const sn = std::max(0.0f, (*symbolNoise)[j]);
                float const localNoise = std::sqrt(tn * sn + 1e-12f);

                auto const applyWhitening = [&](float &value) {
                    float const pre = std::abs(value);
                    sumAbsPre += pre;

                    if (localNoise > 0.0f && std::isfinite(localNoise)) {
                        value /= localNoise;
                    }

                    if (applyErasureInWhitening &&
                        std::abs(value) < erasureThreshold) {
                        value = 0.0f;
                        ++erasures;
                    }

                    sumAbsPost += std::abs(value);
                };

                applyWhitening(result.llr0[i1]);
                applyWhitening(result.llr0[i2]);
                applyWhitening(result.llr0[i4]);
                applyWhitening(result.llr1[i1]);
                applyWhitening(result.llr1[i2]);
                applyWhitening(result.llr1[i4]);
            }
        }

        auto const normalizeLLR = [](auto &llr) {
            float sum = 0.0f;
            float sum_of_squares = 0.0f;

            for (auto const value : llr) {
                sum += value;
                sum_of_squares += value * value;
            }

            float const llrav = sum / llr.size();
            float const llr2av = sum_of_squares / llr.size();
            float const variance = llr2av - llrav * llrav;
            float const llrsig = std::sqrt(variance > 0.0f ? variance : llr2av);

            for (float &val : llr)
                val = (val / llrsig) * 2.83f;
        };

        // Normalize and process metrics

        normalizeLLR(result.llr0);
        normalizeLLR(result.llr1);

        if (whiteningAvailable && debug) {
            auto const total =
                static_cast<double>(result.llr0.size() + result.llr1.size());
            double const avgPre = total > 0.0 ? sumAbsPre / total : 0.0;
            double const avgPost = total > 0.0 ? sumAbsPost / total : 0.0;

            qCDebug(decoder_js8) << "LLR whitening applied"
                                 << "avg|LLR| pre/post:" << avgPre << avgPost
                                 << "erasures:" << erasures;
        }

        result.whiteningApplied = whiteningAvailable;
        result.erasureApplied = applyErasureInWhitening;
        result.erasures = erasures;
        result.avgAbsPre = sumAbsPre;
        result.avgAbsPost = sumAbsPost;
        return result;
    }
};
} // namespace js8