feat(papr): Active Constellation Extension (ACE) — zero-harm PAPR reduction (ULTRA_ACE_PAPR, default off)

Tone reservation doesn't fit our packed spectrum (59 carriers in ~61 in-band
bins, only DC+1 edge spare → would need a frame-geometry redesign). ACE fits:
it extends OUTER constellation points OUTWARD (away from decision boundaries)
to shave time-domain peaks — the RX sees points farther from where it'd
misread them, so BER is equal-or-better, never worse. No reserved carriers,
no frame change, no RX change.

- src/ofdm/papr_ace.hpp: clip-and-project ACE with per-mod outward-safe
  projection (PSK radial; QAM per-axis outer-level). Fixed clip level from
  initial RMS (recomputing chases the rising RMS and stalls at 0.1 dB).
- test_papr_ace: proves both invariants (every point moves only outward,
  pilots/empty bins untouched) + benefit. Measured: QPSK 0.92 / 8PSK 0.82 /
  16QAM 0.83 / 32QAM 0.71 dB reduction, 12/12 improved.
- Wired into modulator createOFDMSymbol, DATA symbols only (genie_capture),
  coherent mods only. ~0.8 dB more average power after peak-normalization.

Unlike the crude clip (rig-measured −58% on clean channels, net −12%), ACE is
strictly non-negative. Verified: ctest 86/86; ACE-on good@20 sim PASS 2700 bps
(no decode regression — sim shows safety, rig shows the power benefit).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019btwFxDt7D19SZSqPYvZnk

Author: secup

src/ofdm/modulator.cpp

@@ -5,7 +5,9 @@
 #include "ultra/logging.hpp"
 #include "demodulator_constants.hpp"
 #include "pilot_pattern.hpp"
+#include "papr_ace.hpp"
 #include "genie_tx_capture.hpp"
+#include "ultra/ofdm_link_adaptation.hpp"
 #include <algorithm>
 #include <random>
 
@@ -280,6 +282,26 @@ struct OFDMModulator::Impl {
             ultra::genie::txCapture().symbols.push_back(freq_domain);
         }
 
+        // ACE PAPR reduction (ULTRA_ACE_PAPR, default off; 2026-07-13). DATA
+        // symbols only (genie_capture marks them — never LTS/probe/preamble, so
+        // sync/channel-estimation waveforms stay pristine) and coherent mods
+        // only. Extends outer constellation points OUTWARD to shave time peaks
+        // → after the TX peak-normalization, ~0.8 dB more average power on the
+        // air, with ZERO harmful EVM (points move only away from decision
+        // boundaries → RX BER equal-or-better). No RX change. Unit-proven in
+        // test_papr_ace. Unlike the crude clip (rig-measured −58% on clean
+        // channels), ACE is strictly non-negative.
+        static const bool ace_enabled = [] {
+            const char* e = std::getenv("ULTRA_ACE_PAPR");
+            return e != nullptr && e[0] != '\0' && e[0] != '0';
+        }();
+        if (ace_enabled && genie_capture &&
+            ultra::ofdm_link_adaptation::isCoherentModulation(config.modulation)) {
+            ofdm::papr_ace::applyAce(freq_domain, data_carrier_indices,
+                               config.modulation, fft,
+                               /*clip_ratio=*/1.6f, /*max_iters=*/8, /*mu=*/1.0f);
+        }
+
         // IFFT to time domain
         auto& time_domain = time_domain_scratch;
         time_domain.resize(config.fft_size);

src/ofdm/papr_ace.hpp

@@ -0,0 +1,205 @@
+#pragma once
+// Active Constellation Extension (ACE) PAPR reduction.
+//
+// WHY ACE (not clipping, not tone reservation) — measured on the rig 2026-07-13:
+//   - Crude amplitude clipping recovers ~4.5 dB of average power (real,
+//     hardware-only benefit under peak-normalization) but injects EVM that
+//     CRATERS clean channels (−58%: it damages a signal the RX decodes fine).
+//   - Tone reservation needs ~4-6 spare in-band carriers; our spectrum is
+//     packed (59 carriers in ~61 in-band bins, only DC+1 edge spare), so it
+//     would require a frame-geometry redesign.
+//   ACE fits a packed spectrum: it extends OUTER constellation points OUTWARD
+//   (away from their decision boundaries) to cancel time-domain peaks. The RX
+//   sees points FARTHER from where it would misread them, so BER is
+//   equal-or-better — never worse. No reserved carriers, no frame change, no
+//   RX change (the demapper's decision regions are unbounded on the outward
+//   side). The two invariants below are what make it safe; the unit test
+//   (test_papr_ace) proves both hold.
+//
+// INVARIANT 1 (safety): every data carrier moves ONLY in its outward-safe
+//   region — radially outward for PSK, axis-outward on an outer level for QAM.
+//   No point moves toward any decision boundary. Pilots and empty bins are
+//   never touched (channel estimation and the reserved bins are preserved).
+// INVARIANT 2 (benefit): post-PAPR <= pre-PAPR (peaks only shrink).
+//
+// Algorithm: clip-and-project (Krongold & Jones 2003). Clip the time signal,
+// take the clip residual's spectrum, add back ONLY the outward-safe component
+// on data carriers, iterate a few times. The projection is what confines the
+// correction to the safe region.
+
+#include "ultra/types.hpp"
+#include "ultra/dsp.hpp"
+#include "ofdm/demodulator_constants.hpp"
+
+#include <algorithm>
+#include <cmath>
+#include <vector>
+
+namespace ultra {
+namespace ofdm {
+namespace papr_ace {
+
+struct AceResult {
+    bool applied = false;
+    float pre_papr_db = 0.0f;
+    float post_papr_db = 0.0f;
+    int iterations = 0;
+    size_t data_carriers_extended = 0;
+};
+
+// Outer-level magnitude (in scaled constellation units) per QAM axis: the
+// point is "outer" on an axis if its coordinate sits beyond the last inner
+// decision boundary, so extending it further out crosses no boundary.
+// 16QAM I/Q levels {-3,-1,1,3}·s → outer at ±3·s, inner/outer boundary at 2·s.
+// 32QAM (cross): I {-3..3}·s, Q {-7..7}·s → outer boundary 2·s (I) / 6·s (Q).
+struct QamAxisSpec {
+    float scale = 0.0f;         // constellation scale (1/sqrt(Es))
+    float i_outer_boundary = 0.0f;  // |I| beyond this ⇒ outer on I
+    float q_outer_boundary = 0.0f;  // |Q| beyond this ⇒ outer on Q
+    bool valid = false;
+};
+
+// QAM16_SCALE lives in modulator.cpp (not the shared demod constants); mirror
+// the value here (1/sqrt(10)) so ACE and the TX constellation agree exactly.
+inline constexpr float kAceQam16Scale = 0.3162277660168379f;  // 1/sqrt(10)
+
+inline QamAxisSpec qamAxisSpec(Modulation mod) {
+    using namespace demod_constants;
+    QamAxisSpec s;
+    if (mod == Modulation::QAM16) {
+        s.scale = kAceQam16Scale;
+        s.i_outer_boundary = 2.0f * kAceQam16Scale;  // between level 1 and 3
+        s.q_outer_boundary = 2.0f * kAceQam16Scale;
+        s.valid = true;
+    } else if (mod == Modulation::QAM32) {
+        s.scale = QAM32_SCALE;
+        s.i_outer_boundary = 2.0f * QAM32_SCALE;  // I levels ±1,±3 → outer ±3
+        s.q_outer_boundary = 6.0f * QAM32_SCALE;  // Q levels ±1..±7 → outer ±7
+        s.valid = true;
+    }
+    return s;
+}
+
+inline bool isPskMod(Modulation mod) {
+    // All constellations whose decisions are by phase sector (points on a
+    // circle) → safe extension is radially outward. QAM8 is the 8PSK
+    // constellation (types.hpp:69), so it belongs here, not with rectangular QAM.
+    return mod == Modulation::DBPSK || mod == Modulation::BPSK ||
+           mod == Modulation::DQPSK || mod == Modulation::QPSK ||
+           mod == Modulation::D8PSK || mod == Modulation::QAM8;
+}
+
+// Project a desired correction `delta` for a data symbol `s` onto its
+// outward-safe region. Returns the allowed part (added to s stays decodable).
+inline Complex aceProject(Complex s, Complex delta, Modulation mod,
+                          const QamAxisSpec& qam) {
+    if (isPskMod(mod)) {
+        // PSK decisions are by phase sector: safe = radially OUTWARD only
+        // (increase magnitude, never rotate). Project delta onto the unit
+        // vector s/|s| and keep only the outward (positive-radial) part.
+        const float mag = std::abs(s);
+        if (mag < 1e-9f) return Complex(0.0f, 0.0f);
+        const Complex u = s / mag;
+        const float radial = delta.real() * u.real() + delta.imag() * u.imag();
+        if (radial <= 0.0f) return Complex(0.0f, 0.0f);
+        return u * radial;
+    }
+    if (qam.valid) {
+        // QAM decisions are per-axis at integer half-levels: safe = extend an
+        // OUTER-level coordinate further out on that axis only. Inner
+        // coordinates are pinned (moving them crosses a boundary).
+        float dI = 0.0f, dQ = 0.0f;
+        if (s.real() > qam.i_outer_boundary && delta.real() > 0.0f) dI = delta.real();
+        else if (s.real() < -qam.i_outer_boundary && delta.real() < 0.0f) dI = delta.real();
+        if (s.imag() > qam.q_outer_boundary && delta.imag() > 0.0f) dQ = delta.imag();
+        else if (s.imag() < -qam.q_outer_boundary && delta.imag() < 0.0f) dQ = delta.imag();
+        return Complex(dI, dQ);
+    }
+    return Complex(0.0f, 0.0f);  // unknown mod → no extension (safe no-op)
+}
+
+inline float paprDb(const std::vector<Complex>& x) {
+    double sum_sq = 0.0, peak_sq = 0.0;
+    for (const auto& v : x) {
+        const double p = static_cast<double>(v.real()) * v.real() +
+                         static_cast<double>(v.imag()) * v.imag();
+        sum_sq += p;
+        if (p > peak_sq) peak_sq = p;
+    }
+    if (sum_sq <= 0.0) return 0.0f;
+    const double mean = sum_sq / static_cast<double>(x.size());
+    return static_cast<float>(10.0 * std::log10(peak_sq / mean));
+}
+
+// In-place ACE on the freq-domain symbol. `clip_ratio` is the peak/RMS target
+// in linear (e.g. 10^(target_db/20)); `mu` is the per-iteration step (0..1);
+// `max_iters` typically 3-4. Data carriers only; pilots/empty bins untouched.
+inline AceResult applyAce(std::vector<Complex>& freq_domain,
+                          const std::vector<int>& data_indices,
+                          Modulation mod, FFT& fft,
+                          float clip_ratio, int max_iters, float mu) {
+    AceResult r;
+    const size_t N = freq_domain.size();
+    if (N == 0 || data_indices.empty() || clip_ratio <= 0.0f) return r;
+    const QamAxisSpec qam = qamAxisSpec(mod);
+    if (!isPskMod(mod) && !qam.valid) return r;  // unsupported mod
+
+    std::vector<Complex> x(N), excess(N), E(N);
+    fft.inverse(freq_domain.data(), x.data());
+    r.pre_papr_db = paprDb(x);
+
+    // FIXED clip level from the INITIAL RMS: ACE extends points outward, which
+    // raises RMS — recomputing A each iteration would chase the rising RMS and
+    // stop clipping (self-defeating; measured 0.1 dB). Holding A at the target
+    // peak level lets successive iterations keep pushing the peak down toward it.
+    double init_sq = 0.0;
+    for (const auto& v : x) init_sq += static_cast<double>(v.real()) * v.real() +
+                                       static_cast<double>(v.imag()) * v.imag();
+    const float init_rms = std::sqrt(static_cast<float>(init_sq / static_cast<double>(N)));
+    const float A = clip_ratio * init_rms;
+    if (A <= 0.0f) return r;
+
+    for (int it = 0; it < max_iters; ++it) {
+        bool any = false;
+        for (size_t i = 0; i < N; ++i) {
+            const float m = std::abs(x[i]);
+            if (m > A) {
+                excess[i] = x[i] * ((m - A) / m);  // the part above the clip level
+                any = true;
+            } else {
+                excess[i] = Complex(0.0f, 0.0f);
+            }
+        }
+        if (!any) break;
+
+        // X-domain rep of the time residual: forward(excess). This FFT
+        // convention has forward∘inverse = identity (the modulator uses
+        // inverse for X→time), so no 1/N — E[bin] is already in freq_domain's
+        // units, ready to add to a data carrier.
+        fft.forward(excess.data(), E.data());
+        size_t extended = 0;
+        for (int bin : data_indices) {
+            const Complex s = freq_domain[bin];
+            // Subtract the residual on this carrier (reduces the peak), but only
+            // the outward-safe component.
+            const Complex delta_desired = E[bin] * (-mu);
+            const Complex allowed = aceProject(s, delta_desired, mod, qam);
+            if (allowed.real() != 0.0f || allowed.imag() != 0.0f) {
+                freq_domain[bin] = s + allowed;
+                ++extended;
+            }
+        }
+        r.data_carriers_extended = std::max(r.data_carriers_extended, extended);
+        fft.inverse(freq_domain.data(), x.data());
+        r.iterations = it + 1;
+        if (extended == 0) break;  // nothing safe left to do
+    }
+
+    r.post_papr_db = paprDb(x);
+    r.applied = r.iterations > 0;
+    return r;
+}
+
+}  // namespace papr_ace
+}  // namespace ofdm
+}  // namespace ultra

tests/CMakeLists.txt

@@ -46,6 +46,13 @@ target_include_directories(test_papr_reduction PRIVATE
     ${CMAKE_SOURCE_DIR}/thirdparty/pocketfft)
 add_test(NAME PaprReduction COMMAND test_papr_reduction)
 
+# ACE PAPR reduction — invariant proofs (points move only outward; PAPR down).
+add_executable(test_papr_ace test_papr_ace.cpp)
+target_link_libraries(test_papr_ace PRIVATE ultra_core ota_channel_core)
+target_include_directories(test_papr_ace PRIVATE
+    ${CMAKE_SOURCE_DIR}/src ${CMAKE_SOURCE_DIR}/thirdparty/pocketfft)
+add_test(NAME PaprAce COMMAND test_papr_ace)
+
 add_executable(test_real_hf_loop_channel test_real_hf_loop_channel.cpp)
 target_link_libraries(test_real_hf_loop_channel PRIVATE ota_channel_core)
 add_test(NAME RealHfLoopChannel COMMAND test_real_hf_loop_channel)

tests/test_papr_ace.cpp

@@ -0,0 +1,119 @@
+// ACE PAPR reduction — proves the two safety invariants and the benefit.
+#include "ofdm/papr_ace.hpp"
+#include "ultra/dsp.hpp"
+
+#include <cstdio>
+#include <random>
+#include <vector>
+
+using namespace ultra;
+using ultra::ofdm::papr_ace::applyAce;
+using ultra::ofdm::papr_ace::AceResult;
+using ultra::ofdm::papr_ace::qamAxisSpec;
+using ultra::ofdm::papr_ace::isPskMod;
+
+namespace {
+int g_failures = 0;
+void check(bool ok, const char* msg) {
+    if (!ok) { std::printf("FAIL: %s\n", msg); ++g_failures; }
+}
+
+// Build a random OFDM freq-domain symbol for `mod` on `data_indices`.
+std::vector<Complex> makeSymbol(Modulation mod, const std::vector<int>& data_indices,
+                                size_t fft, uint32_t seed) {
+    std::mt19937 rng(seed);
+    std::vector<Complex> X(fft, Complex(0, 0));
+    const auto qam = qamAxisSpec(mod);
+    for (int bin : data_indices) {
+        if (isPskMod(mod)) {
+            int npsk = (mod == Modulation::QAM8 || mod == Modulation::D8PSK) ? 8
+                       : (mod == Modulation::DBPSK || mod == Modulation::BPSK) ? 2 : 4;
+            float ph = (2.0f * float(M_PI) / npsk) * (rng() % npsk) +
+                       ((npsk == 4) ? float(M_PI) / 4.0f : 0.0f);
+            X[bin] = Complex(std::cos(ph), std::sin(ph));
+        } else {
+            // QAM: pick random levels
+            const float sI = qam.scale;
+            int iL, qL;
+            if (mod == Modulation::QAM16) { int L[4]={-3,-1,1,3}; iL=L[rng()%4]; qL=L[rng()%4]; }
+            else { int LI[4]={-3,-1,1,3}; int LQ[8]={-7,-5,-3,-1,1,3,5,7}; iL=LI[rng()%4]; qL=LQ[rng()%8]; }
+            X[bin] = Complex(iL * sI, qL * sI);
+        }
+    }
+    return X;
+}
+
+// Decision-region check: does the ACE'd point still decode to the SAME symbol
+// as the original (i.e. it only moved within/beyond its own region)?
+bool sameDecision(Complex orig, Complex aced, Modulation mod) {
+    const auto qam = qamAxisSpec(mod);
+    if (isPskMod(mod)) {
+        // phase sector unchanged, magnitude only grew
+        int npsk = (mod == Modulation::QAM8 || mod == Modulation::D8PSK) ? 8
+                   : (mod == Modulation::DBPSK || mod == Modulation::BPSK) ? 2 : 4;
+        float sector = 2.0f * float(M_PI) / npsk;
+        float d = std::arg(aced * std::conj(orig));  // phase change
+        bool phase_ok = std::abs(d) < sector * 0.499f;
+        bool mag_ok = std::abs(aced) >= std::abs(orig) - 1e-4f;  // outward (or unchanged)
+        return phase_ok && mag_ok;
+    }
+    // QAM: each coordinate must stay in the same level bin (or extend an outer one out)
+    auto axisOk = [](float o, float a, float outer) {
+        if (o > outer) return a >= o - 1e-4f;      // was +outer, only grew
+        if (o < -outer) return a <= o + 1e-4f;     // was -outer, only grew (more negative)
+        return std::abs(a - o) < 1e-4f;            // inner: must be pinned
+    };
+    return axisOk(orig.real(), aced.real(), qam.i_outer_boundary) &&
+           axisOk(orig.imag(), aced.imag(), qam.q_outer_boundary);
+}
+
+void testMod(Modulation mod, const char* name) {
+    const size_t fft = 1024;
+    // 59 carriers, k=-29..30 skip 0 (production layout)
+    std::vector<int> data_indices;
+    for (int k = -29; k <= 30; ++k) {
+        if (k == 0) continue;
+        data_indices.push_back((k + int(fft)) % int(fft));
+    }
+    FFT fftp(fft);
+    int improved = 0, samples = 12;
+    double total_reduction = 0.0;
+    for (int t = 0; t < samples; ++t) {
+        auto X = makeSymbol(mod, data_indices, fft, 0x1000u + t * 131u);
+        auto X0 = X;  // original (pre-ACE)
+        AceResult r = applyAce(X, data_indices, mod, fftp,
+                               /*clip_ratio=*/1.6f, /*max_iters=*/10, /*mu=*/1.0f);
+        // INVARIANT 2: PAPR did not increase
+        check(r.post_papr_db <= r.pre_papr_db + 0.05f, "PAPR must not increase");
+        if (r.post_papr_db < r.pre_papr_db - 0.1f) ++improved;
+        total_reduction += (r.pre_papr_db - r.post_papr_db);
+        // INVARIANT 1: every data carrier still decodes to its original symbol
+        for (int bin : data_indices) {
+            if (!sameDecision(X0[bin], X[bin], mod)) {
+                check(false, "data carrier left its decision region");
+                break;
+            }
+        }
+        // pilots/empty bins untouched
+        for (size_t i = 0; i < fft; ++i) {
+            bool is_data = false;
+            for (int b : data_indices) if (int(i) == b) { is_data = true; break; }
+            if (!is_data) check(std::abs(X[i] - X0[i]) < 1e-6f, "non-data bin modified");
+        }
+    }
+    std::printf("  %-6s: mean PAPR reduction %.2f dB, improved %d/%d\n",
+                name, total_reduction / samples, improved, samples);
+    check(improved >= samples / 2, "ACE should reduce PAPR on most symbols");
+}
+}  // namespace
+
+int main() {
+    std::printf("== ACE PAPR reduction: invariants + benefit ==\n");
+    testMod(Modulation::QPSK, "QPSK");
+    testMod(Modulation::QAM8, "8PSK");
+    testMod(Modulation::QAM16, "16QAM");
+    testMod(Modulation::QAM32, "32QAM");
+    if (g_failures == 0) std::printf("PASS: ACE invariants hold; PAPR reduced.\n");
+    else std::printf("FAIL: %d check(s) failed.\n", g_failures);
+    return g_failures == 0 ? 0 : 1;
+}