Flux Lens

What It Is 🧠

The Flux Lens is a context-level diagnostic that computes a spectral energy-transfer spectrum from a 1D field and uses it to maintain a tapered bandpass reconstruction in both spectral and physical space.

It is designed to answer:

• Where is the dominant spectral energy transfer? (kc)
• How concentrated is that transfer? (k50, k90)
• What does the corresponding band-limited signal look like? (band_phys, band_spec)

Note

Flux Lens is currently implemented for 1D fields only. If the selected field has rank ≠ 1, lens.valid is false.

---

Mathematical Formulation 📐

The Flux Lens uses a skew-Burgers spectral flux to estimate inter-scale energy transfer.

Given a real or complex field $u$ with spectral coefficients $\hat{u}(k)$:

Step 1 — Nonlinear term. Form the squared field $u^2$ and FFT it to get $\widehat{u^2}(k)$. Compute the skew-Burgers nonlinear term:

$$\hat{N}(k) = -\frac{i}{2}\, k\, \widehat{u^2}(k)$$

Step 2 — Mode-by-mode energy exchange rate. The work done by mode $k$:

$$S(k) = \operatorname{Re}\!\left[\overline{\hat{u}(k)}\cdot\hat{N}(k)\right]$$

where $\overline{(\cdot)}$ denotes the complex conjugate.

Step 3 — Cumulative flux. Sort modes by $|k|$ and accumulate:

$$\Pi(K) = \sum_{|k| \leq K} S(k)$$

$\Pi(K)$ is the net energy flux from scales larger than $K$ to scales smaller than $K$. Peaks and sign changes identify dominant energy cascades.

Marks derived from $\Pi$:

Dealiasing. When use_dealias = true, all modes above the 2/3 rule cutoff are zeroed before the nonlinear product:

$$k_{\text{cut}} = \frac{2}{3}\, k_{\max}$$

---

Quick Start 🚀

1. Enable the lens with flux_lens_set_enabled(ctx, true).
2. Optionally select a field with flux_lens_set_field_index.
3. Read scalars from ooc.flux_lens(ctx) and arrays from lens:buckets() / lens:band().

---

API 📚

Create Proxy

local lens = ooc.flux_lens(ctx)

Returns a step-cached snapshot proxy. Fields are read lazily; the proxy refreshes automatically at step boundaries. Call lens:refresh() to force an immediate update.

Snapshot Fields

Proxy Methods

---

Array Layouts 📊

Buckets

local b = lens:buckets()
-- b.k[i]    : wavenumber |k| of bucket i
-- b.S[i]    : energy exchange rate S(k)
-- b.absS[i] : |S(k)|
-- b.pi[i]   : cumulative flux Π(k)
-- All arrays have the same length: lens.bucket_count

Band

local band = lens:band()
-- band.spec[i] : spectral-domain complex sample {re, im}
-- band.phys[i] : physical-domain complex sample {re, im}
-- Both arrays have length: lens.band_capacity

---

Control Functions 🧰

All control functions take ctx as the first argument and return true on success, false if the lens is not initialised.

Enable / Disable

ooc.flux_lens_set_enabled(ctx, true)     -- enable (allocates FFT buffers on first use)
ooc.flux_lens_set_enabled(ctx, false)    -- disable (frees internal buffers)
ooc.flux_lens_force_refresh(ctx)         -- trigger immediate recompute regardless of update_period

Field Selection

ooc.flux_lens_set_field_index(ctx, index)   -- 0-based integer index

Update Rate & Smoothing

Lock & Band Manipulation

ooc.flux_lens_set_locked(ctx, true)       -- freeze band_lo/hi; marks still update
ooc.flux_lens_set_locked(ctx, false)      -- allow band to track marks automatically

ooc.flux_lens_scale_width(ctx, scale)     -- multiply (band_hi − band_lo) by scale (>1 wider, <1 narrower)
ooc.flux_lens_shift_center(ctx, shift)    -- translate band center by shift in |k| units

scale_width and shift_center operate on the current band_lo/hi when the lens has a valid snapshot, otherwise on target_band_lo/hi.

Direct Band Bounds

ooc.flux_lens_set_band_low(ctx, k_low)    -- set band_lo explicitly; auto-locks the lens
ooc.flux_lens_set_band_high(ctx, k_high)  -- set band_hi explicitly; auto-locks the lens

Tip

flux_lens_set_band_low and flux_lens_set_band_high automatically call flux_lens_set_locked(ctx, true) if the lens is not already locked — preventing mark-based updates from overriding your explicit bounds on the next recompute.

---

Examples 🧪

Minimal enable + marks readout

ooc.flux_lens_set_enabled(ctx, true)
ooc.flux_lens_set_update_period(ctx, 30)

local lens = ooc.flux_lens(ctx)
ooc.step(ctx)

lens:refresh()
if lens.valid then
    ooc.log("kc=%.3f  k50=%.3f  k90=%.3f  pi_max=%.4f",
        lens.kc, lens.k50, lens.k90, lens.pi_max)
end

Slow refresh + lock band at current marks

ooc.flux_lens_set_enabled(ctx, true)
ooc.flux_lens_set_update_period(ctx, 200)

for i = 1, 500 do ooc.step(ctx) end

ooc.flux_lens_force_refresh(ctx)
local lens = ooc.flux_lens(ctx)
lens:refresh()

ooc.flux_lens_set_locked(ctx, true)
ooc.log("band locked at [%.2f, %.2f]", lens.band_lo, lens.band_hi)

Explicit band bounds with direct setters

ooc.flux_lens_set_enabled(ctx, true)
ooc.flux_lens_set_band_low(ctx, 2.0)    -- auto-locks
ooc.flux_lens_set_band_high(ctx, 8.0)  -- already locked; updates hi bound only

local lens = ooc.flux_lens(ctx)
lens:refresh()
ooc.log("band=[%.1f, %.1f]  locked=%s", lens.band_lo, lens.band_hi, tostring(lens.locked))

Select which field drives the lens

local a = ooc.add_field(ctx, {512}, { type = "complex_double", fill = {0, 0} })
local b = ooc.add_field(ctx, {512}, { type = "complex_double", fill = {0, 0} })

ooc.flux_lens_set_enabled(ctx, true)
ooc.flux_lens_set_field_index(ctx, 1)   -- 0-based field index

Bucket export for analysis

ooc.flux_lens_force_refresh(ctx)
local lens = ooc.flux_lens(ctx)
lens:refresh()

local b = lens:buckets()
for i = 1, #b.k do
    ooc.log("k=%.3f  S=%+.4f  Pi=%.4f", b.k[i], b.S[i], b.pi[i])
end

Band-limited physical signal

ooc.flux_lens_set_enabled(ctx, true)
ooc.flux_lens_set_smoothing(ctx, 0.05)
ooc.flux_lens_set_min_bandwidth(ctx, 1.0)

for i = 1, 100 do ooc.step(ctx) end

local lens = ooc.flux_lens(ctx)
lens:refresh()
if lens.band_ready then
    local band = lens:band()
    local mid  = math.floor(lens.band_capacity / 2) + 1
    ooc.log("band phys centre: %.4f + %.4fi", band.phys[mid][1], band.phys[mid][2])
end