diff --git a/Cargo.lock b/Cargo.lock
index 7d516f55..daf50864 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -958,6 +958,12 @@ dependencies = [
"windows-link",
]
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
[[package]]
name = "libredox"
version = "0.1.10"
@@ -1073,6 +1079,7 @@ dependencies = [
"ash",
"clap",
"ctrlc",
+ "libm",
"mutate-assets",
"mutate-slide",
"mutate-vulkan",
@@ -1081,6 +1088,7 @@ dependencies = [
"pipewire",
"pm-remez",
"ringbuf",
+ "rustfft",
"thiserror 2.0.18",
]
@@ -1806,6 +1814,15 @@ dependencies = [
"zerocopy",
]
+[[package]]
+name = "primal-check"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc0d895b311e3af9902528fbb8f928688abbd95872819320517cc24ca6b2bd08"
+dependencies = [
+ "num-integer",
+]
+
[[package]]
name = "proc-macro-crate"
version = "3.5.0"
@@ -2000,6 +2017,20 @@ version = "2.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "357703d41365b4b27c590e3ed91eabb1b663f07c4c084095e60cbed4362dff0d"
+[[package]]
+name = "rustfft"
+version = "6.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21db5f9893e91f41798c88680037dba611ca6674703c1a18601b01a72c8adb89"
+dependencies = [
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "primal-check",
+ "strength_reduce",
+ "transpose",
+]
+
[[package]]
name = "rustix"
version = "0.38.44"
@@ -2203,6 +2234,12 @@ version = "1.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+[[package]]
+name = "strength_reduce"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fe895eb47f22e2ddd4dabc02bce419d2e643c8e3b585c78158b349195bc24d82"
+
[[package]]
name = "strict-num"
version = "0.1.1"
@@ -2416,6 +2453,16 @@ version = "0.1.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b9d12581f227e93f094d3af2ae690a574abb8a2b9b7a96e7cfe9647b2b617678"
+[[package]]
+name = "transpose"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ad61aed86bc3faea4300c7aee358b4c6d0c8d6ccc36524c96e4c92ccf26e77e"
+dependencies = [
+ "num-integer",
+ "strength_reduce",
+]
+
[[package]]
name = "trybuild"
version = "1.0.116"
diff --git a/Cargo.toml b/Cargo.toml
index 24924671..e2032884 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -37,8 +37,10 @@ winit = "0.30.12"
# DSP
aligned = "0.4.3"
+libm = "0.2.16"
num-complex = "0.4.6"
num-traits = "0.2.19"
+rustfft = "6.4.1"
# PMR
pm-remez = "0.2.5"
diff --git a/DEBT.md b/DEBT.md
index 2b1603b9..255757a0 100644
--- a/DEBT.md
+++ b/DEBT.md
@@ -82,6 +82,8 @@ This will also require the assets loader and the pipeline macros to learn how to
Keep stuffing slang into the visualizer. It's wrong. The cost is mainly changing some paths later, but when we start to want libraries to pull together more common operations and newtypes, it will become more urgent to fix this.
+The existing hashing needs an update with `-depfile ` to store a list of dependencies. Only if zero dependencies change can we skip a build. We need an escape hatch env variable in case dependencies are based on some discovery change instead of file contents. Use `-no-codegen` for faster re-generation. We can possibly use cargo's `rerun-if-changed` a little better.
+
## Externally Synchronized
We can't use [some Vulkan resources](https://docs.vulkan.org/spec/latest/chapters/fundamentals.html#fundamentals-threadingbehavior) concurrently with some other usages. This isn't a huge concern yet. Queue submission is a common case. Each queue just uses a `Mutex` on the submissions. De-aliasing overloaded queues was the harder problem than synchronizing them.
diff --git a/README.md b/README.md
index e06c378a..08429b92 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@
...real-time programs that display impressive graphics, music, and mind-blowing effects sometimes considered impossible given the limits of the hardware - The Incredible Demoscene
- The need to be smaller drives more sophistication, not less. It also drives faster iteration. µTate (/ˈmjuːteɪt/) gives researchers developing post-attention heuristics a path to quick viability for their work without stacks of H200's and petabytes of data. Music visualization that learns online demands more efficiency. The techniques required will apply far beyond music, reaching into hard problems that will enable the next round of breakthroughs.
+ The need to be smaller drives more sophistication, not less. µTate (/ˈmjuːteɪt/) gives researchers developing post-attention heuristics a path to quick viability for their work without running stacks of H200's and access to petabytes of data. Music visualization that learns online demands more efficiency. The techniques required will apply far beyond music, reaching into hard problems that will enable the next round of breakthroughs.
### Contents
@@ -31,22 +31,22 @@
## Building the Alliance
-Bringing together a wide group of overlapping interests creates opportunities to solve problems that no one beneficiary could easily approach alone. Technology that is both upstream of a huge consumer market and has even bigger downstream applications makes new things possible.
+µTate directly provides synchronize visuals for live music performances or casual home entertainment visualization. As a library, µTate uses gaming-adjacent technologies like [slang](https://shader-slang.org/) because these enable us to tap into demand for things like more natural procedural content and more organic animation.
-µTate's direct usages provide synchronized visuals for live music performances or casual home entertainment visualization. µTate uses gaming-adjacent technologies like [slang](https://shader-slang.org/) because these enable us to tap into demand for things like better artificial intelligence and more natural procedural content, tuned with feedback from a live renderer.
+Bringing together a wide group of overlapping interests creates opportunities to solve problems that no one beneficiary could easily approach alone. Technology that is upstream of a huge consumer market has an engine. That engine can push downstream applications that make new things possible.
-Incidentally, the common parts of the problems will emit open source implementations of critical components for others to advance in their own fields. Today's neural rendering can feed into tomorrow's heuristics toolkits that enable fast iteration on multi-disciplinary problems with prohibitive search spaces, problems like using synthetic biology to more cheaply make sustainable aviation fuel so that supersonic international travel becomes trivial.
+Incidentally, the common parts of the problems will emit open source implementations for others to use to advance in their own fields. Today's neural rendering can feed into tomorrow's heuristics toolkits that enable fast iteration on multi-disciplinary problems.
## The Vulkan Engine
-µTate's online learning goals require some specific runtime capabilities that will incidentally create a user-friendly declarative graphics programming interface. The design phase complete, and this is what we are building:
+µTate's online learning goals require some specific runtime capabilities that **will** incidentally create a user-friendly declarative graphics programming interface. The **design phase** is complete, and this is what we are building:
-- **Host-shader Type Agreement** - Use slang reflection data and Rust proc-macro fan-in to verify type and layout agreement of declared sets of pipeline stages.
-- **Declarative Resources** - Enable pipelines to specify the geometry and semantic type of upstream inputs, intermediate buffers, and outputs.
-- **Resource Runtime** - Maintain a single state of what should be loaded and to operate reconciliation processes to continually maintain the intended state.
-- **Workload Management** - Requesting resources fed by upstream dispatches and external processes like pipewire should spin up those processes to feed those input buffers.
-- **Memory management** - Maintain sub-allocations, epoch recycling, and borrow counts for shared resources in use by multiple independent downstreams. Support aliasing.
-- **Reactive Argument Injection** - Enable command recording for pipelines to pick up pointer swaps and other dynamic values from a single source, decoupling the recorder from knowledge of the specific upstream sources. Enable publishes to affect the correct epoch without knowledge of the downstream.
+- **Host-shader Type Agreement** - Use slang reflection data and Rust proc-macro fan-in to verify type and layout agreement of declared sets of pipeline stages and control data like push constants.
+- **Resource Runtime** - Maintain a single goal state of what should be loaded and to operate reconciliation loops to continually approach and then maintain the intended state.
+- **Declarative Resources** - Enable pipelines to specify the geometry and semantic type of upstream inputs, intermediate buffers, and outputs to validating pipeline remixing. Deferred resource creation for free.
+- **Workload Management** - Depending on resources fed from upstream dispatches and external processes like pipewire should spin up the upstreams.
+- **Memory management** - Maintain sub-allocations, epoch recycling, and borrow counts for shared resources in use by multiple independent downstreams.
+- **Reactive Argument Injection** - Enable command recording for pipelines to pick up pointer swaps, screen size changes, and other dynamic values from a single source. This decouples the recorder from knowledge of the specific upstream sources. Enable publishing updates to affect the correct dependents without knowledge of what is downstream.
The argument injection and declarative resource spin-up mean composing pipelines does not require any knowledge of how to provision them. This enables machine learning to focus on declaring how to draw, modulating arguments, and which data to use. Meanwhile the runtime will put those declarations into effect.
@@ -60,13 +60,13 @@ With regards to safety, the strategy being taken is to start with guard rails of
## The DSP
-µTate is bringing real-time DSP onto the GPU so that prohibitively expensive on-CPU techniques can be done at conspicuously high resolutions in real time, directly adjacent to the video pipelines that need that output. 4k filter banks with multiple high-quality Goertzel filters and wide-band IIRs are intended to provide sources of neat textures, modulation signals to move things with the music, and inputs for real-time beat detection & inference.
+µTate does DSP directly on the GPU at conspicuously high resolutions, directly adjacent to the video and machine learning pipelines that need that output. The 4k filter bank provides a neat texture source, modulation signals to move things with the music, and inputs for online learning & inference.
-Past visualizers users simple beat detection based on simple heuristics like volume thresholds. These are easily faked out. They don't understand patterns or layering. Only a handful of dynamic values and waveform textures were available to preset authors, so the results were inevitably highly abstract programmer art that cannot reflect the mood or spirit of the music being played. Compared to traditional heuristics, these high quality procedural inputs will enable:
+Past visualizers users simple beat detection based on simple heuristics like volume thresholds and envelopes. These are easily faked out. They can never understand patterns or layering. They will also never reflect the mood or spirit of the music being played. Compared to traditional heuristics, modern machine learning techniques can:
- Distinguish layered melodies and instrument changes.
- Interpret timbre and texture to create visuals unique to how an instrument is played on that particular day.
-- Beat **prediction** and visual cues when something *is expected*.
+- **Predict** beats, using visual cues to indicate when something *is expected* soon.
- Automating visual "hard cuts" when prediction fails, following the change in musical tone with changes in visual tone.
## The Machine Learning
@@ -97,7 +97,7 @@ The internal `mutate-vulkan` crate is intended to become a competent Vulkan runt
### DSP Workbench
-`cargo workbench --help` will list the CLI interface for the workbench, a CLI program being developed to assist in engineering filter bank configurations for use on the GPU. A separate `pmr` bin (requires pm_remez) can generate static FIR filter settings. Try `cargo pmr lowpass --taps 23`.
+`cargo workbench --help` will list the CLI interface for the workbench, a CLI program being developed to assist in engineering filter bank configurations for use on the GPU. A separate `pmr` bin (requires pm_remez) can generate static FIR filter weights. Try `cargo pmr lowpass --taps 23`.
## Contributing
diff --git a/crates/assets/src/build.rs b/crates/assets/src/build.rs
index f06b6293..fe6d4aa1 100644
--- a/crates/assets/src/build.rs
+++ b/crates/assets/src/build.rs
@@ -5,6 +5,13 @@
//!
//! This module contains the build time functionality.
+// NEXT use -no-codegen -reflection-json to push forward library-vs-shader decisions and tie to
+// hash
+// DEBT shader libraries. Without `-dep-file` testing, we have no idea which hashes to check and
+// therefore we don't know if we should recompile. The "build system" metadata belongs in a
+// directory and maybe out of history, so maybe all of these files get a gitignore soon.
+// NEXT Going to fun times to Nixify 🫠
+
use std::{
ffi, fs,
io::{BufReader, Read, Write},
@@ -15,7 +22,6 @@ use std::{
use xxhash_rust::xxh3::Xxh3;
/// Use slangc to recursively compile shaders from shaders to assets/shaders.
-// NEXT emit metadata from slangc
pub fn build_shaders() {
let manifest_dir = &std::env::var("CARGO_MANIFEST_DIR").unwrap();
let crate_root = Path::new(manifest_dir);
@@ -61,7 +67,7 @@ pub fn build_shaders() {
let status = process::Command::new("slangc")
.arg(path.as_os_str())
.arg("-I")
- .arg("shaders/lib")
+ .arg(src_root.join("lib"))
.arg("-fvk-use-scalar-layout")
.arg("-o")
.arg(out)
diff --git a/crates/vulkan/src/device/memory/mod.rs b/crates/vulkan/src/device/memory/mod.rs
index abbdf8c8..9588f1f5 100644
--- a/crates/vulkan/src/device/memory/mod.rs
+++ b/crates/vulkan/src/device/memory/mod.rs
@@ -53,6 +53,9 @@
// NOTE staging + transfer is an operation that can be abstracted over by a runtime as part of an
// optionally two-step provision. Explicit BAR is reported, but mainly so that applications
// expecting it don't fall over.
+// NEXT Really wanted to switch to a byte based API for MappedAllocation, which feels too much like
+// an array style API. That shape might work, but right now it's conflated with use of mapped
+// memory. This module sucks. Just punch it until it has the types it needs to.
pub mod bar;
@@ -423,7 +426,7 @@ mod test {
#[test]
pub fn resolve_all_domains() {
- with_context!(|device, instance| {
+ with_context!(|instance, device| {
let memory = &device.memory;
println!("\n=== memory types present ===");
diff --git a/crates/vulkan/src/device/mod.rs b/crates/vulkan/src/device/mod.rs
index e861fde3..bf170521 100644
--- a/crates/vulkan/src/device/mod.rs
+++ b/crates/vulkan/src/device/mod.rs
@@ -7,6 +7,9 @@
//! tables. The [`Device`] pulls all of these behaviors together. [`Device`] derefs to the raw
//! [`ash::vk::device`] for direct use in ash APIs.
+// MAYBE Extend vk::Device for things that don't require the wrapped Device. Then &Device grows
+// those methods via Deref.
+
pub mod descriptors;
pub mod fence;
pub mod memory;
diff --git a/crates/vulkan/src/device/queue.rs b/crates/vulkan/src/device/queue.rs
index e0d8fc94..14b842f2 100644
--- a/crates/vulkan/src/device/queue.rs
+++ b/crates/vulkan/src/device/queue.rs
@@ -759,7 +759,7 @@ mod test {
#[test]
fn graphics_high_always_exact() {
- with_context!(|device, instance| {
+ with_context!(|instance, device| {
// obtaining device context implicitly created queues
let gfx = device.queues.graphics_offscreen(QueuePriority::High);
assert_eq!(gfx.priority, QueuePriority::High);
@@ -773,7 +773,7 @@ mod test {
#[test]
fn transfer_is_always_low_priority() {
- with_context!(|device, _instance| {
+ with_context!(|_instance, device| {
let compute_low = device.queues.compute(QueuePriority::Low);
let transfer = device.queues.transfer();
// If compute had to be overloaded onto graphics high (degenerate case) then this test
@@ -791,7 +791,7 @@ mod test {
#[test]
fn compute_low_is_always_low_priority() {
- with_context!(|device, _instance| {
+ with_context!(|_instance, device| {
let gfx_low = device.queues.graphics_offscreen(QueuePriority::Low);
let compute_low = device.queues.compute(QueuePriority::Low);
// If graphics had to be overloaded onto graphics high (degenerate case) then this test
@@ -809,7 +809,7 @@ mod test {
#[test]
fn dedicated_transfer_when_present() {
- with_context!(|device, instance| {
+ with_context!(|instance, device| {
let physical = device.physical_device;
let instance = &instance.raw;
diff --git a/crates/vulkan/src/dispatch/pool.rs b/crates/vulkan/src/dispatch/pool.rs
index 152ad4c1..a7577934 100644
--- a/crates/vulkan/src/dispatch/pool.rs
+++ b/crates/vulkan/src/dispatch/pool.rs
@@ -339,7 +339,7 @@ mod test {
#[test]
fn pool_instantiate() {
- with_context!(|device, instance| {
+ with_context!(|instance, device| {
let queue = device
.queues
.graphics_offscreen(QueuePriority::Low)
@@ -351,7 +351,7 @@ mod test {
#[test]
fn pool_buffer_create() {
- with_context!(|device, instance| {
+ with_context!(|instance, device| {
let queue = device
.queues
.graphics_offscreen(QueuePriority::Low)
@@ -368,7 +368,7 @@ mod test {
#[test]
fn ring_instantiate() {
- with_context!(|device, instance| {
+ with_context!(|instance, device| {
let queue = device
.queues
.graphics_offscreen(QueuePriority::Low)
@@ -380,7 +380,7 @@ mod test {
#[test]
fn acquire_pool() {
- with_context!(|device, instance| {
+ with_context!(|instance, device| {
let queue = device
.queues
.graphics_offscreen(QueuePriority::Low)
diff --git a/crates/vulkan/src/dispatch/submit.rs b/crates/vulkan/src/dispatch/submit.rs
index 1ef4f166..4913f544 100644
--- a/crates/vulkan/src/dispatch/submit.rs
+++ b/crates/vulkan/src/dispatch/submit.rs
@@ -42,6 +42,7 @@
// that are laid out in order already, matching Vulkan's use of slices when assembling the
// submission for the C API.
// NEXT protected support can likely inherit from the queue or command buffer.
+// MAYBE get rid of fences on most submissions?
use std::marker::PhantomData;
use std::mem::MaybeUninit;
@@ -279,7 +280,7 @@ pub mod test {
#[test]
fn start_submission() {
- with_context!(|device, instance| {
+ with_context!(|instance, device| {
let start = device
.queues
.compute(QueuePriority::High)
@@ -290,7 +291,7 @@ pub mod test {
#[test]
fn empty_signal() {
- with_context!(|device, instance| {
+ with_context!(|instance, device| {
let mut semaphore = device.make_timeline_semaphore().unwrap();
let signal_intent = semaphore.next_signal();
let wait_value = signal_intent.wait_value();
@@ -310,7 +311,7 @@ pub mod test {
#[test]
fn binary_semaphores() {
- with_context!(|device, _instance| {
+ with_context!(|_instance, device| {
let queue = device
.queues
.graphics_offscreen(QueuePriority::High)
diff --git a/crates/vulkan/src/instance/mod.rs b/crates/vulkan/src/instance/mod.rs
index 0a9007f9..dd7f7285 100644
--- a/crates/vulkan/src/instance/mod.rs
+++ b/crates/vulkan/src/instance/mod.rs
@@ -346,7 +346,7 @@ impl Instance {
if caps.pipeline_executable_info {
exts.push(vk::KHR_PIPELINE_EXECUTABLE_PROPERTIES_NAME);
}
- SupportedDevice::new(physical_device, self, &exts, self.profile, caps)
+ SupportedDevice::new( self, physical_device, &exts, self.profile, caps)
})
.collect()
}
@@ -580,9 +580,9 @@ impl std::ops::Deref for Instance {
/// });
///
/// // With both context and instance:
-/// with_context!(|device, instance| {
-/// // `device: Device` is available here
+/// with_context!(|instance, device| {
/// // `instance: Instance` is available here
+/// // `device: Device` is available here
/// });
/// ```
#[macro_export]
@@ -596,7 +596,7 @@ macro_rules! with_context {
instance.destroy();
__result
}};
- (|$device:ident, $instance:ident| $($body:tt)*) => {{
+ (|$instance:ident, $device:ident| $($body:tt)*) => {{
let mut $instance = $crate::instance::Instance::new_headless();
let mut physical_device = $instance.supported_devices(&[]).remove(0);
let mut $device = physical_device.into_logical(&$instance);
@@ -653,7 +653,7 @@ pub struct SupportedDevice {
}
impl SupportedDevice {
- fn new(physical_device: vk::PhysicalDevice, instance: &Instance, extensions: &[&'static CStr],
+ fn new(instance: &Instance, physical_device: vk::PhysicalDevice, extensions: &[&'static CStr],
profile: InstanceProfile, caps: DeviceCaps) -> SupportedDevice {
let name = unsafe {
let props =
diff --git a/crates/vulkan/src/pipeline/mod.rs b/crates/vulkan/src/pipeline/mod.rs
index 4971d647..742d0e88 100644
--- a/crates/vulkan/src/pipeline/mod.rs
+++ b/crates/vulkan/src/pipeline/mod.rs
@@ -244,6 +244,10 @@ impl ComputePipeline {
}
}
+ pub fn into_raw(self) -> vk::Pipeline {
+ self.pipeline
+ }
+
pub fn destroy(self, device: &Device) {
unsafe {
device.destroy_pipeline(self.pipeline, None);
diff --git a/crates/vulkan/src/present/mod.rs b/crates/vulkan/src/present/mod.rs
index ce810bd3..b911c1ce 100644
--- a/crates/vulkan/src/present/mod.rs
+++ b/crates/vulkan/src/present/mod.rs
@@ -42,11 +42,11 @@ pub struct PresentRing {
impl PresentRing {
pub fn new(
- device: &Device,
instance: &Instance,
+ device: &Device,
surface: &Surface,
) -> Result {
- let swapchain = Swapchain::new(device, instance, surface)?;
+ let swapchain = Swapchain::new(instance, device, surface)?;
// SAFETY: Present ring must live within the backing Device lifetime.
let queue = device
.queues
diff --git a/crates/vulkan/src/present/swapchain.rs b/crates/vulkan/src/present/swapchain.rs
index 6655323f..ad48d33e 100644
--- a/crates/vulkan/src/present/swapchain.rs
+++ b/crates/vulkan/src/present/swapchain.rs
@@ -267,8 +267,8 @@ pub struct Swapchain {
impl Swapchain {
pub fn new(
- device: &Device,
instance: &Instance,
+ device: &Device,
surface: &Surface,
) -> Result {
let Instance {
diff --git a/crates/vulkan/src/resource/buffer.rs b/crates/vulkan/src/resource/buffer.rs
index cc907a0b..92d315a3 100644
--- a/crates/vulkan/src/resource/buffer.rs
+++ b/crates/vulkan/src/resource/buffer.rs
@@ -23,6 +23,12 @@
// DEBT sub-allocation / resource runtime. 💸
// NEXT hang buffer & image creation methods off of the device.memory. Limit buffer & image module
// scope to handling post-allocation.
+// DEBT DMA vs transfer abstraction. The control data should be written device visible and then
+// copied / handed off into device-only memory. We would initialize this lazily, only beginning
+// dispatches when the upload of control data is available and black-holing (later shared consumers
+// will need a concept of the reclaim owner) data to keep upstream ring slack available. There's a
+// lot of runtime spec hydration and downstream dependency concepts in there.
+// NEXT separate static and dynamic data. Use UBO buffer flags etc.
use std::ptr::NonNull;
@@ -53,10 +59,13 @@ pub struct MappedAllocation {
impl MappedAllocation {
/// `len` is the number of `T` this buffer will hold.
pub fn new(device: &Device, len: usize) -> Result {
+ let padded_size = ((std::mem::size_of::() * len) as u64)
+ .next_multiple_of(device.memory.non_coherent_atom_size);
+
// NEXT these are pretty temporito. See the abstract choices in the memory module. That's
// basically how we want to do this.
let buffer_info = vk::BufferCreateInfo {
- size: (std::mem::size_of::() * len) as u64,
+ size: padded_size.into(),
usage: vk::BufferUsageFlags::STORAGE_BUFFER
| vk::BufferUsageFlags::TRANSFER_DST
| vk::BufferUsageFlags::TRANSFER_SRC
@@ -64,13 +73,14 @@ impl MappedAllocation {
sharing_mode: vk::SharingMode::EXCLUSIVE,
..Default::default()
};
- let (buffer, memory, size) = device
+ let (buffer, memory, padded_size) = device
.memory
.allocate_buffer(&buffer_info, MemoryUse::Upload)?;
+
let raw_ptr = unsafe {
device
.as_raw()
- .map_memory(memory, 0, size, vk::MemoryMapFlags::empty())?
+ .map_memory(memory, 0, padded_size, vk::MemoryMapFlags::empty())?
};
let ptr = NonNull::new(raw_ptr as *mut T).unwrap();
Ok(Self {
@@ -78,7 +88,7 @@ impl MappedAllocation {
ptr,
len,
memory,
- size,
+ size: padded_size,
})
}
diff --git a/crates/vulkan/src/resource/retired.rs b/crates/vulkan/src/resource/retired.rs
index 47d78fb6..a497ce3f 100644
--- a/crates/vulkan/src/resource/retired.rs
+++ b/crates/vulkan/src/resource/retired.rs
@@ -251,7 +251,7 @@ mod test {
use super::*;
pub fn delete_some_semaphores() {
- with_context!(|device, instance| {
+ with_context!(|instance, device| {
// XXX find some ways to test... Need API calls that don't explode so we can test
// ticking and rotation
let semaphore = device.make_timeline_semaphore().unwrap();
diff --git a/crates/vulkan/src/slang/mod.rs b/crates/vulkan/src/slang/mod.rs
index f49f9669..4f6870a5 100644
--- a/crates/vulkan/src/slang/mod.rs
+++ b/crates/vulkan/src/slang/mod.rs
@@ -166,6 +166,7 @@
// LLMs are getting pretty cracktastic good at these "find the needle" problems where the type of X
// is slightly off. Deciding how to lay out control data? That is some exceedingly boring code
// that could use some macros later.
+// NEXT automatically promote u32 -> UInt32 and newtypes thereof
// XXX Might be possible to pull more information up onto the GpuType and leave GpuScalar and
// GpuPrimitive split in order support float3 etc as simply as possible.
// XXX Buffer Device Address destination payload types not implemented
@@ -175,6 +176,7 @@
// XXX Remove need for double (or more) calls of into or inner for user-defined newtypes.
// XXX Newtype for newtypes tests (and define how to interpret this)
// XXX Finish up some Deref implementations and tests
+// XXX DeviceAddress and vk::DeviceAddress are too redundant.
// NEXT we are definitely implementing vectors (ie float3) as leaf types (`GpuPrimitive`) to avoid
// vector complexity infecting calculations for struct fields and enums.
diff --git a/examples/minimal/src/main.rs b/examples/minimal/src/main.rs
index b8c0d808..527ae09e 100644
--- a/examples/minimal/src/main.rs
+++ b/examples/minimal/src/main.rs
@@ -44,7 +44,7 @@ impl WindowContext {
let (tx, rx) = std::sync::mpsc::channel::();
let mut surface = Surface::new(instance, device, raw_surface, window).unwrap();
let handle = std::thread::spawn(move || {
- let mut present_ring = PresentRing::new(device, instance, &surface).unwrap();
+ let mut present_ring = PresentRing::new(instance, device, &surface).unwrap();
let extent = surface.extent();
let mut renderer = HelloDraw::new(device);
renderer.provision(device, extent).unwrap();
diff --git a/mutate-lib/Cargo.toml b/mutate-lib/Cargo.toml
index 293d617c..4905fdec 100644
--- a/mutate-lib/Cargo.toml
+++ b/mutate-lib/Cargo.toml
@@ -20,6 +20,8 @@ ash.workspace = true
aligned = {workspace = true, optional = true}
num-complex = {workspace = true, optional = true}
num-traits = {workspace = true, optional = true}
+rustfft = {workspace = true, optional = true}
+libm = {workspace = true, optional = true}
# workbench dependencies
clap = {workspace = true, features=["derive"], optional = true}
@@ -43,9 +45,15 @@ path = "src/pipewire.rs"
[features]
default = ["dsp"]
-# DEBT move tree into dsp
-dsp = ["dep:num-complex", "dep:num-traits", "dep:mutate-slide", "dep:aligned"]
vulkan = ["dep:mutate-vulkan"]
+
+# DEBT move tree into dsp
+dsp = ["dep:num-complex", "dep:num-traits", "dep:mutate-slide", "dep:aligned", "dep:libm"]
+# Running alternative wavelet generation methods requires rustfft. These
+# demonstrate accuracy up to the precision convergence of the alternative
+# methods.
+# LIES validation is a feature of DSP, not a dependent.
+validate = ["dep:rustfft", "dsp"]
workbench = ["dep:clap", "dsp"]
pmr = ["dep:pm-remez", "dep:clap", "dsp"]
diff --git a/mutate-lib/src/audio/import.rs b/mutate-lib/src/audio/import.rs
index 829638df..3970ed34 100644
--- a/mutate-lib/src/audio/import.rs
+++ b/mutate-lib/src/audio/import.rs
@@ -49,18 +49,17 @@
//!
//! // A minimal callback that just returns the number of occupied samples, enabling the upstream to
//! // reclaim the entire ring after each callback.
-//! let callback = |view| {return view.occupied_len()};
+//! let callback = |view| {return view.read_count() };
//!
//! // Initialize a stream onto the device (initialization not shown);
-//! let stream = context.import_to_device::<2, _>(&device, &choice, 48_000, "mutate", callback)?;
+//! let stream = context.import_to_device::<2, _>(&device, &choice, 6_000, "µTate", callback)?;
//!
//! ```
//!
//! ### Memory Layout
//!
-//! A single device allocation is used for control data and all channels. Each channel is laid out
-//! in a single contiguous sub-allocation but with slight padding for the device flush atom size.
-//! Call [`channel_offsets`] to obtain these sub-allocation offsets.
+//! A single allocation is used for all channels and data is stored planar, not interleaved.
+//! Channel zero is left by convention.
//!
//! ## Ownership
//!
@@ -68,30 +67,16 @@
//! `AudioConsumer` owns the upstream pipewire stream (`AudioConnection`, not the entire
//! `AudioContext`).
-// DEBT We've hit a mildly intersection between manual drop of Vulkan resources (which require
-// owning a device pointer in order to drop) and the tombstone style cooperative drop of either end
-// of audio server connections. If the Vulkan resources could be dropped into a deletion queue, we
-// don't really need to change `Device` ownership physics because ownership of drop-queue capable
-// references becomes decoupled from logical device. Resource management can't come soon enough.
-// DEBT Tbh, we don't need the intermediate consumer ring. If we read into host-mapped memory,
-// release the pipewire chunks, and then flush, we are just as fast as when using an intermediate
-// ring. Consistent visibility for consumers is the last concern that may motivate an intermediate
-// ring buffer. We have to update control data. The initial pipewire read doesn't want to wait on
-// that. Currently we are also de-interleaving to planar for SoA on the device. Pipewire can do
-// the de-interleaving, but this will require work on pipewire side to support multiple rings on the
-// process callback side.
// DEBT Sample formats.
-// NOTE Channels are doing a fairly naive sub-allocation that could be re-derived on demand.
-// Storing the full array of offsets was chosen to duplicate less logic on the device.
-// NEXT sub-allocation alignments were not designed for wide loads. Vectorized reading of the ring
-// is a bit more complex for the consumer, more complexity than it's worth on this pass.
+// NEXT sub-allocation alignments were not designed for wide loads. Just support vectorized reading
+// in case a consumer wants that.
// NEXT consumer hazard tracking and slack rotation-reclaim support on producer so that
-// discontinuities are swallowed faster and without being presented to the consumer.
-// DEBT pipewire mis-indirection. We may still need one set of hooks outside pipewire because our
-// model is to put one callback in pipewire. After the main connection takes ownership of the
-// pipewire chunks, we want to run a callback to write to the GPU ring. Multiple downstreams can
-// dispatch on that as soon as it's written, either notifying a thread owned by the downstream or
-// just doing the dispatch synchronously.
+// discontinuities are swallowed faster and without restart discontinuities being presented to the
+// consumer.
+// DEBT pipewire mis-indirection. We don't need an intermediate ring in the AudioConsumer. A simple
+// copy into mapped memory, with or without intermediate buffer to allow pipewire to reclaim as soon
+// as possible, would do just fine. Pipewire probably can de-interleave faster already, but we have
+// to request it that way.
use std::sync::{
atomic::{AtomicBool, AtomicU64, Ordering},
@@ -106,58 +91,12 @@ use crate::vulkan::prelude::*;
use crate::MutateError;
pub(crate) mod core {
- pub use super::{AudioImport, ChannelRegion, DeviceRingView, DeviceSpan};
-}
-
-/// When dispatching a shader, provide the base address as a buffer and read `len` samples.
-/// Physical index straddles will be returned as two spans, and dispatching twice is appropriate.
-/// Barrier insertion is **not** needed because flushed ranges are guaranteed safe for read until
-/// your [`ImportSink`] allows reclaim, which **must** only be called after the dispatch is retired.
-#[derive(Clone, Copy, Debug)]
-pub struct DeviceSpan {
- pub base: vk::DeviceAddress,
- /// Length in *samples*, not bytes. Callers multiply by the sample stride.
- pub len: u32,
-}
-
-/// One channel's occupied region, expressed as device spans.
-///
-/// `Contiguous` means a single dispatch covers the channel. `Split` means the
-/// occupied region wraps the ring end and needs two dispatches (or one dispatch
-/// that handles two spans).
-#[derive(Clone, Copy, Debug)]
-pub enum ChannelRegion {
- Contiguous(DeviceSpan),
- Split { head: DeviceSpan, tail: DeviceSpan },
-}
-
-impl ChannelRegion {
- /// Total occupied samples across the region's spans.
- pub fn occupied_len(&self) -> u32 {
- match self {
- ChannelRegion::Contiguous(s) => s.len,
- ChannelRegion::Split { head, tail } => head.len + tail.len,
- }
- }
-
- /// True when the consumer must dispatch over two spans.
- pub fn is_split(&self) -> bool {
- matches!(self, ChannelRegion::Split { .. })
- }
-
- /// Spans in logical (oldest-first) order, for uniform iteration.
- pub fn spans(&self) -> impl Iterator- {
- let (a, b) = match self {
- ChannelRegion::Contiguous(s) => (Some(*s), None),
- ChannelRegion::Split { head, tail } => (Some(*head), Some(*tail)),
- };
- a.into_iter().chain(b)
- }
+ pub use super::{AudioImport, DeviceAudioView};
}
// NOTE this struct is probably very close to dead.
struct Control {
- // MAYBE wrap up state into the untorn.
+ // MAYBE wrap up state into the Untorn.
/// Writer has completed writes up to this logical address
write_head: AtomicU64,
/// Reader has allowed reclaim up to this logical address
@@ -166,116 +105,62 @@ struct Control {
closed: AtomicBool,
}
-/// Immutable ring geometry. Copy + Send, so both the host handle and the writer thread hold
-/// their own. Owns the wrap math so it exists in exactly one place.
+/// Downstream readers dispatch against the data using this output type.
#[derive(Clone, Copy, Debug)]
-pub struct RingLayout {
- /// Backing memory buffer device address.
- pub base_address: vk::DeviceAddress,
- /// An array of buffer offsets for each ring's sub-allocation. Base address + offset =
- /// on-device address.
- pub channel_offsets: [u32; CHANNELS],
- /// Length of each channel
+pub struct DeviceAudioView {
+ /// device address.
+ pub base_address: DeviceAddress,
+ /// Length of each channel in samples.
pub sample_count: u32,
-}
-
-impl RingLayout {
- /// Snapshot the occupied region for every channel from a single head read.
- ///
- /// All channels share the same logical [read, write) interval, so the wrap
- /// geometry is computed once and only the per-channel base address differs.
- pub fn regions(&self, read: u64, write: u64) -> [ChannelRegion; CHANNELS] {
- let cap = self.sample_count as u64;
- debug_assert!(read <= write, "read head passed write head");
- debug_assert!(write - read <= cap, "occupied exceeds capacity");
- let occupied = write - read;
- let first = read % cap;
- let to_end = cap - first;
- let split = occupied > to_end;
-
- std::array::from_fn(|c| {
- let base = self.base_address + self.channel_offsets[c] as u64;
- let phys_addr = |s: u64| base + s * 4;
- if split {
- ChannelRegion::Split {
- head: DeviceSpan {
- base: phys_addr(first),
- len: to_end as u32,
- },
- tail: DeviceSpan {
- base,
- len: (occupied - to_end) as u32,
- },
- }
- } else {
- ChannelRegion::Contiguous(DeviceSpan {
- base: phys_addr(first),
- len: occupied as u32,
- })
- }
- })
- }
-}
-
-/// A snapshot of ring state and consumer-owned data that will be valid for use in a dispatch.
-/// Callback **must** advance the `read_head` by returning the number of reetired samples or else
-/// the producer will just fill up. Advancing the read head allows the producer to reclaim, meaning
-/// the data could be overwritten and flushed.
-///
-/// Many methods accept a `local_read_head` which should be a value tracked by your downstream, such
-/// the farthest advance you have dispatched so far. The index after the last sample you read
-/// should be your new `local_read_head`. If you are smoothly tracking timing data and want to
-/// allow some buffer to prevent underruns on audio server stutter, do not consume up until read,
-/// but instead use the `AudioTiming` data.
-#[derive(Clone, Debug)]
-pub struct DeviceRingView {
- pub ring_layout: RingLayout, // add Copy to RingLayout
- pub timing: AudioTiming,
- /// Logical heads at snapshot time.
+ /// number of channels
+ pub channel_count: u32,
+ /// Output rate of data arriving on this ring. Samples per second.
+ pub sample_rate: u32,
+ /// Logical write head at snapshot time.
pub write_head: u64,
+ /// Consumer owned logical read head.
pub read_head: u64,
+ /// Upstream filtered timing signal to enable smooth tracking. Only available after the first
+ /// chunk is published by the audio server.
+ pub timing: Option,
}
-impl DeviceRingView {
- /// Total number of samples in the ring. If you return a positive intent to reclaim, you must
- /// not use more than the difference between samples and reclaim or else undefined behavior may
- /// occur.
- pub fn occupied_len(&self) -> u32 {
+impl DeviceAudioView {
+ /// Convert logical read head to a pre-wrapped physical index. Shaders usually start reading
+ /// here.
+ pub fn read_head_physical(&self) -> u32 {
+ (self.read_head % self.sample_count as u64) as u32
+ }
+
+ /// Convert occupied length to a count for use with a physical start index and the wrap mask.
+ pub fn read_count(&self) -> u32 {
(self.write_head - self.read_head) as u32
}
- /// Obtain the ring data starting at `local_read_head`.
- pub fn regions_since(&self, local_read_head: u64) -> [ChannelRegion; CHANNELS] {
- debug_assert!(
- local_read_head >= self.read_head,
- "local head behind reclaim head"
- );
- debug_assert!(
- local_read_head <= self.write_head,
- "local head ahead of write head"
- );
- self.ring_layout.regions(local_read_head, self.write_head)
+ /// Wrap modulus for physical indexing.
+ pub fn mask(&self) -> u32 {
+ self.sample_count - 1
}
- /// Like `occupied_len` but only includes samples starting at `local_read_head`.
- pub fn occupied_since(&self, local_read_head: u64) -> u32 {
- debug_assert!(local_read_head <= self.write_head);
- (self.write_head - local_read_head) as u32
+ /// Compute a device address of a specific channel. Not expecting much use, but a single
+ /// channel reader may prefer it.
+ pub fn channel(&self, channel_index: usize) -> DeviceAddress {
+ (self.base_address.raw() + channel_index as u64 * self.sample_count as u64 * 4).into()
}
}
-/// Import data consumer. Receives [`DeviceRingView`] snapshot when new data has been published to
-/// the on-device rings. Implemented for `Send + 'static` closures.
-pub trait ImportSink: Send + 'static {
- /// Return samples the caller is done with; the writer folds that into the read head.
- fn process(&mut self, view: &DeviceRingView) -> Result;
+/// User callback type that receives published updates of the device audio rings. Implemented for
+/// `Send + 'static` closures.
+pub trait ImportSink: Send + 'static {
+ /// Callback must return retired sample count.
+ fn process(&mut self, view: &DeviceAudioView) -> Result;
}
-impl ImportSink for F
+impl ImportSink for F
where
- F: FnMut(&DeviceRingView) -> Result + Send + 'static,
+ F: FnMut(&DeviceAudioView) -> Result + Send + 'static,
{
- fn process(&mut self, view: &DeviceRingView) -> Result {
+ fn process(&mut self, view: &DeviceAudioView) -> Result {
self(view)
}
}
@@ -283,110 +168,78 @@ where
/// The owned side a device import stream. Data import to the GPU is handled by an owned a reader
/// thread. This type gathers up ownership and provides an interface to the published control data
/// for host-side and setting up device-side reads.
-pub struct AudioImport {
+pub struct AudioImport {
/// Just a persistent bag of bytes being used for ad-hoc sub-allocations. (DEBT).
buffer: MappedAllocation,
/// Reader thread.
read_thread_handle: Option>>,
/// Address, offsets of each channel, length in samples.
- ring_layout: RingLayout,
+ ring_layout: DeviceAudioView,
/// Shared control data.
control: Arc,
}
-impl AudioImport {
- /// Allocate the ring backing store and derive its geometry, without starting import.
- ///
- /// Split out from construction so a caller can build an [`ImportSink`] that already knows the
- /// `RingLayout` (device addresses, channel offsets, capacity) before the reader thread — and
- /// therefore the first callback — exists. Hand the result to [`Self::with_allocation`].
+impl AudioImport {
+ /// Create an import from the audio server to the device, using `AudioConsumer` as an embodiment
+ /// of `AudioChoice` until we cut out the middle man (see mis-indirection DEBT).
///
/// `sample_count` is the length of each channel's ring buffer in samples. More buffer means
/// less potential for bursts leading to discontinuities.
- pub fn allocate(
- device: &Device,
- sample_count: u32,
- ) -> Result<(MappedAllocation, RingLayout), MutateError> {
- let non_coherent_atom_size = device.memory.non_coherent_atom_size;
- let channel_bytes = sample_count as u64 * 4;
- // rounded up for atom flush size
- let channel_stride = channel_bytes.next_multiple_of(non_coherent_atom_size as u64);
- let size = channel_stride as usize * CHANNELS;
- let channel_offsets: [u32; CHANNELS] =
- std::array::from_fn(|i| (channel_stride * i as u64) as u32);
- let mut buffer: MappedAllocation = MappedAllocation::new(device, size)?;
- let base_address = buffer.device_address(device)?;
-
- // f32 0.0 is all-zero bytes, so this write is safe.
- buffer.as_mut_slice().fill(0u8);
- buffer.flush(device)?;
-
- Ok((
- buffer,
- RingLayout {
- base_address,
- channel_offsets,
- sample_count,
- },
- ))
- }
-
- /// `sample_count` is the length of each channel's ring buffer in samples. More buffer means
- /// less potential for bursts leading to discontinuities.
- ///
- /// Use [`Self::allocate`] + [`Self::with_allocation`] when the sink needs the layout up front.
- pub(crate) fn new>(
- device: &Device,
- rx: AudioConsumer,
- sample_count: u32,
- import_sink: S,
- ) -> Result, MutateError> {
- let (buffer, ring_layout) = Self::allocate(device, sample_count)?;
- Self::new_inner(device, rx, buffer, ring_layout, import_sink)
- }
-
- /// Start import over an allocation obtained from [`Self::allocate`]. The `RingLayout` must be
- /// the one returned alongside that buffer; pairing a layout with a different allocation is
- /// undefined behavior on the device side.
- pub fn with_allocation>(
- device: &Device,
- rx: AudioConsumer,
- allocation: (MappedAllocation, RingLayout),
- import_sink: S,
- ) -> Result, MutateError> {
- let (buffer, ring_layout) = allocation;
- Self::new_inner(device, rx, buffer, ring_layout, import_sink)
- }
-
- fn new_inner>(
+ pub fn new(
device: &Device,
mut rx: AudioConsumer,
- mut buffer: MappedAllocation,
- ring_layout: RingLayout,
+ sample_count: u32,
mut import_sink: S,
- ) -> Result, MutateError> {
+ ) -> Result {
let control = Arc::new(Control {
write_head: AtomicU64::new(0),
read_head: AtomicU64::new(0),
closed: AtomicBool::new(false),
});
- // Re-derive what the writer loop needs from the layout it was allocated against.
- let non_coherent_atom_size = device.memory.non_coherent_atom_size;
- let sample_count = ring_layout.sample_count;
- let channel_offsets = ring_layout.channel_offsets;
- // rounded up for atom flush size; must match `allocate`
- let channel_stride =
- (sample_count as u64 * 4).next_multiple_of(non_coherent_atom_size as u64);
+ // DEBT the `rx` has no idea how many channels it has 🤡🤦
+ let channel_count: u32 = 2;
+ let (buffer, ring_layout) = {
+ let size = sample_count * 4 * channel_count;
+ let mut buffer: MappedAllocation = MappedAllocation::new(device, size as usize)?;
+
+ // f32 0.0 is all-zero bytes, so this write is safe.
+ buffer.as_mut_slice().fill(0u8);
+ buffer.flush(device)?;
+
+ // LIES Just made up the rate and channel count to work downstream
+ // DEBT sample rate / channel count. The fix can likely be implemented incidental to
+ // getting rid of the intermediate consumer, so let's do that.
+ let base_address = buffer.device_address(device)?;
+ (
+ buffer,
+ DeviceAudioView {
+ base_address: base_address.into(),
+ channel_count: 2,
+ sample_count: sample_count as u32,
+ sample_rate: 48_000,
+ read_head: 0,
+ write_head: 0,
+ timing: None,
+ },
+ )
+ };
+
+ // Planar layout we will de-interleave into.
+ let channel_bytes = sample_count as usize * 4;
+ let total_bytes = channel_bytes * channel_count as usize;
+ let channels = channel_count as usize;
+
// Owned write view for the thread.
- // NOTE in a perfect world, we would figure out the mutability or mark unsafe. Until that
- // world exists, this just works.
+ // NOTE write view mutability story is not worked out at all, but not super critical here
+ // either. There's one canonical writer, the audio server.
let mut view = buffer.write_view(device);
+
let writer_control = control.clone();
- let mut timing = rx.timing()?;
+ let mut timing = Some(rx.timing()?);
let read_thread_handle = Some(std::thread::spawn(move || {
- let mut scratch = vec![0u8; 4 * CHANNELS * sample_count as usize];
+ let mut scratch = vec![0u8; (4 * channel_count * sample_count) as usize];
let mut write_head: u64 = 0;
let mut read_head: u64 = 0;
@@ -397,8 +250,9 @@ impl AudioImport {
// it from the pipewire ingestion ring to our scratch buffer.
Ok(_got) => {
let read = rx.read(&mut scratch)?;
- let frame_bytes = 4 * CHANNELS;
- // NOTE not checking for partial samples as pipewire seems well-behaved so far.
+ let frame_bytes = (4 * channel_count) as usize;
+
+ // NOTE not checking for partial frames as pipewire seems well-behaved so far.
let incoming = read / frame_bytes;
let occupied = write_head - read_head;
debug_assert!(occupied <= sample_count as u64);
@@ -416,56 +270,20 @@ impl AudioImport {
// Scatter interleaved input samples across channels
// DEBT the interleaved assumption here can break pretty spectacularly.
- for c in 0..CHANNELS {
- let ring_base = channel_offsets[c] as usize;
+ for c in 0..channels {
+ let ring_base = c * channel_bytes;
for s in 0..to_write {
- let src = (s * CHANNELS + c) * 4;
+ let src = (s * channels + c) * 4;
let logical = (start + s as u64) % sample_count as u64;
let dst_byte = ring_base + logical as usize * 4;
dst[dst_byte..dst_byte + 4].copy_from_slice(&scratch[src..src + 4]);
}
}
- // Per-channel flush. One run if the written region is contiguous, two if it
- // wraps the ring end. Ring slots are 4 bytes. ring_base is stride-aligned.
- // NOTE over-flushing just means more coherence traffic and will not
- // affect the contents of slots that were not modified.
- let atom = non_coherent_atom_size as u64;
- let cap = sample_count as u64;
-
- // NOTE flush is no-op on coherent memory. We are tending to put this in
- // BAR memory, but our buffer type wrappers are super immature, so we don't
- // know what kind of memory was actually given to us yet.
- for c in 0..CHANNELS {
- let ring_base = channel_offsets[c] as u64;
- let first = start % cap;
- let end = (start + to_write as u64) % cap;
- let wrapped = to_write != 0 && end <= first;
- let flush_run =
- |view: &mut MappedWriteView,
- lo_sample: u64,
- hi_sample: u64|
- -> Result<(), MutateError> {
- // Byte range [lo, hi) within the channel, widened to atom alignment.
- let lo = ring_base + lo_sample * 4;
- let hi = ring_base + hi_sample * 4;
- // NOTE atom is PoT. Equivalent expression is (lo / atom) * atom
- let lo_aligned = lo & !(atom - 1);
- let hi_aligned = hi
- .next_multiple_of(atom)
- .min(ring_base + channel_stride as u64);
- Ok(view.flush_range(lo_aligned, hi_aligned - lo_aligned)?)
- };
-
- if to_write == 0 {
- // nothing to flush
- } else if wrapped {
- flush_run(&mut view, first, cap)?; // head: [first, cap)
- flush_run(&mut view, 0, end)?; // tail: [0, end)
- } else {
- flush_run(&mut view, first, end)?; // contiguous: [first, end)
- }
- }
+ // NOTE flush is a no-op on coherent memory. Whole-buffer flush costs some
+ // coherence traffic but never changes unmodified slots, and the written
+ // ranges are annoying to compute per channel across a wrap.
+ view.flush_range(0, total_bytes as u64)?;
// Publish new write head
write_head += to_write as u64;
@@ -476,23 +294,21 @@ impl AudioImport {
// Pick up new timing data, which is written by now.
match rx.timing() {
Ok(new_time) => {
- timing = new_time;
+ timing = Some(new_time);
}
Err(e) => {
// Realistically poisoning was the only error type. Suddenly closed
- // upstream still has a phase, just one that will never arrive again.
+ // upstream still has a phase estimate, just one that will never
+ // arrive again.
return Err(e);
}
};
// Ring update is flushed & coherent. Host view of state is updated. Call
- // the callback with the updated view, including the latest timing data and
- // a pointer to the read_head so that it can update it.
- let device_ring_view = DeviceRingView {
- ring_layout,
- timing,
- read_head,
- write_head,
- };
+ // the callback with the updated view, including the latest timing data.
+ let mut device_ring_view = ring_layout.clone();
+ device_ring_view.timing = timing;
+ device_ring_view.write_head = write_head;
+ device_ring_view.read_head = read_head;
let retired = match import_sink.process(&device_ring_view) {
Ok(retired) => retired as u64,
@@ -508,7 +324,7 @@ impl AudioImport {
writer_control.read_head.store(read_head, Ordering::Release);
}
Err(MutateError::Timeout(_)) => {
- // DEBT logging and runtime toggles for scopes of messages 💀
+ // DEBT tracing and environment toggles for scoped logging 💀
println!("audio server chunk was late");
}
Err(e) => {
@@ -528,37 +344,6 @@ impl AudioImport {
})
}
- /// The size in elements that the physical rings can store when full. This is also the repeat
- /// modulus for physical indexes.
- pub fn capacity(&self) -> u32 {
- self.ring_layout.sample_count
- }
-
- /// Number of samples currently occupied (written but not reclaimed).
- /// This is the same for every channel — they advance in lockstep.
- pub fn occupied_len(&self) -> Result {
- if self.control.closed.load(Ordering::Relaxed) {
- return Err(MutateError::Dropped);
- }
- // XXX These two reads can tear. Pair the reads with Untorn.
- let read = self.control.read_head.load(Ordering::Acquire);
- let write = self.control.write_head.load(Ordering::Acquire);
- Ok(write.saturating_sub(read) as u32)
- }
-
- /// Physical base address of each channel's ring sub-allocation. **Bare use of these addresses
- /// is undefined behavior** that will read torn data. Use for fun or ring diagnostics. All bit
- /// patterns are valid float, but the data found may be nonsensical and pollute heuristics.
- /// That said, observing the data tearing in real time is **pretty rad** 😎!
- pub unsafe fn channels(&self) -> Result<[vk::DeviceAddress; CHANNELS], MutateError> {
- if self.control.closed.load(Ordering::Relaxed) {
- return Err(MutateError::Dropped);
- }
- Ok(std::array::from_fn(|c| {
- self.ring_layout.base_address + self.ring_layout.channel_offsets[c] as u64
- }))
- }
-
/// Will set a flag for upstream and returns when that thread joins. This method blocks.
pub fn destroy(&mut self, device: &Device) -> Result<(), MutateError> {
// tombstone, join the reader thread, and destroy the allocation.
diff --git a/mutate-lib/src/audio/mod.rs b/mutate-lib/src/audio/mod.rs
index ae43a2d9..0610fc04 100644
--- a/mutate-lib/src/audio/mod.rs
+++ b/mutate-lib/src/audio/mod.rs
@@ -346,21 +346,20 @@ impl AudioContext {
Ok(AudioConsumer { conn })
}
- /// Connect a stream and import it into a device-side ring.
+ /// Connect a stream and import it into a device-side set of ring buffers.
///
- /// `CHANNELS` is the planar channel count laid out on the device; `sample_count`
- /// is the per-channel ring length in samples. Both are fixed at call time.
+ /// `sample_count` is the per-channel ring length in samples.
#[cfg(feature = "vulkan")]
- pub fn import_to_device(
+ pub fn import_to_device
(
&self,
device: &Device,
choice: &AudioChoice,
sample_count: u32,
name: &str,
import_sink: S,
- ) -> Result, MutateError>
+ ) -> Result
where
- S: import::ImportSink,
+ S: import::ImportSink,
{
let rx = self.connect(choice, name)?;
import::AudioImport::new(device, rx, sample_count, import_sink)
diff --git a/mutate-lib/src/bin/pmr.rs b/mutate-lib/src/bin/pmr.rs
index 43f6c70c..6b19769c 100644
--- a/mutate-lib/src/bin/pmr.rs
+++ b/mutate-lib/src/bin/pmr.rs
@@ -3,26 +3,32 @@
//! # Parks McClellen Remez (PMR)
//!
-//! This utility will output static PMR windows weights.
+//! This utility will output FIR filter weights for downsampling. The `pm_remez` crate was pretty
+//! heavy, so this small binary is the only thing that depends on it.
//!
-//! The `pm_remez` crate was pretty heavy, so this small binary is the only thing that depends on it.
-//! We are currently only using PMR to generate low pass filters for downsampling. We have a neat
-//! trick on our side:
+//! We have a neat trick on our side:
//!
-//! - We have already analyzed high frequency bins using the normal input stream.
+//! - We will have already analyzed high frequency bins using the normal input stream.
//! - We can begin our transition in bins we won't read in the output anyway.
//! - That region is consecutive with the region that will fold into it after downsampling.
//! - We use both already read bins and their folding mirror as an ultra-wide transition band.
//!
//! We're cheating and letting some noise fold in, but are attenuating it enough that it's
-//! definitely not growing. Anything that remains will be further obliterated by our DFT bins and
-//! IIR pre-conditioning. The important part is that **no noise folds into bands we will be looking
-//! at with DFTs.**
+//! definitely not growing. Anything that remains will be further obliterated by our other filters
+//! and The important part is that **no noise folds into bands we will be looking at.**
//!
-//! This leaves us some tradeoffs to shoot for:
+//! After exploiting that design trick, we make some tradeoffs based on what we're doing.
//!
-//! - Noise floor in the stop (which would fold into our new bands of interest!)
-//! - Acceptable folding noise in the transition.
+//! - Noise floor in the stop, which would fold into our new bands of interest, must be crushed to
+//! pieces. Pieces!
+//! - Noise from the fold in the transition should at least be attenuated. We don't want our pass
+//! band filters to be working harder due to folded noise that is both more intense and nearer in
+//! pitch.
+//! - Acceptable ripple in the pass (signal we are definitely looking at). A few dB of droop in the
+//! pass will be nothing compared to being able to use 70dB dynamic range by crushing the stop
+//! band.
+//! - If a filter is not terminal, we can allow it to ripple more in the early pass band because a
+//! lower rate will be read by those bins in the bank.
//! - **Short FIR length and very acceptable delays.**
//! - Phase linearity and all the good stuff that FIRs bring.
//!
@@ -31,18 +37,29 @@
//! Within this repo:
//!
//! ```sh
-//! cargo pmr lowpass --taps 23
+//! cargo pmr lowpass --taps 25
//! ```
//!
-//! As a standalone binary:
+//! Fully flat pass band down to DC (the last, lowest downsampler)
//!
//! ```sh
-//! pmr estimate-bins --passband-edge 0.125
-//! pmr --help
+//! cargo pmr lowpass --taps 25 --terminal
+//! ```
+//!
+//! Wider margin for main lobes in the pass band to not get scalloped by the transition.
+//!
+//! ```sh
+//! cargo pmr lowpass --taps 25 --guard 0.25
//! ```
// NEXT it would be welcome to just reduce the weight of the pm_remez crate. The calculation seems
// super fast if only it didn't bring in a bunch of dependencies.
+// NEXT not appropriate for calibration. We keep finding better weight combinations. Well, why not
+// automate some of the search for our actual priorities?
+// NEXT DFT the outputs and quit "sine seweeeeping".
+// NOTE No wonder this crate seemed like slop to some. Note, it was sloppy, not slop. Slop has a
+// floor. Humans can go lower. 💩
+// NEXT Just get rid of length estimation. Our designs don't work with it at all.
use clap::{Parser, Subcommand, ValueEnum};
use pm_remez::{
@@ -53,6 +70,7 @@ use pm_remez::{
use mutate_lib as utate;
use utate::dsp::{fir::DynamicFirLowpass, Filter, SineSweeper};
+// XXX LOL. Good thinking!
#[derive(Debug, thiserror::Error)]
enum PmrError {
#[error("Unhandled error: {0}")]
@@ -72,49 +90,51 @@ struct EntryPoint {
enum Command {
/// Output optimal FIR lowpass filter weights.
Lowpass(LowpassArgs),
- /// Estimate the required FIR length from qualitative goals.
- EstimateBins(EstimateArgs),
+}
+
+fn ranged_f64(s: &str, lo: f64, hi: f64) -> Result {
+ let v: f64 = s.parse().map_err(|_| format!("`{s}` is not a number"))?;
+ if (lo..=hi).contains(&v) {
+ Ok(v)
+ } else {
+ Err(format!("must be in {lo}..={hi}"))
+ }
+}
+
+fn read_fraction(s: &str) -> Result {
+ ranged_f64(s, 0.05, 0.95)
+}
+
+fn guard_fraction(s: &str) -> Result {
+ ranged_f64(s, 0.0, 0.9)
+}
+
+fn decimate_factor(s: &str) -> Result {
+ let v: usize = s.parse().map_err(|_| format!("`{s}` is not an integer"))?;
+ if v >= 2 && v.is_power_of_two() {
+ Ok(v)
+ } else {
+ Err("must be a power of two, at least 2".into())
+ }
}
#[derive(Debug, clap::Args)]
struct LowpassArgs {
+ /// Decimation factor applied after this filter. Sets the target Nyquist.
+ #[arg(long, default_value_t = 2, value_parser = decimate_factor)]
+ pub decimate: usize,
/// Number of samples that influence each output.
#[arg(long)]
pub taps: Option,
- /// Beginning of pass band as a fraction of the input sample rate.
- #[arg(long)]
- pub pass: Option,
- /// Beginning of the stop band as a fraction of the input sample rate.
- #[arg(long)]
- pub stop: Option,
- // NEXT adjust attenuation vs pass goals. The scale of weights in the stop band trades ripple
- // in the pass (and transition) for depth of cut in the stop band, which is most important for
- // us.
- /// Use just a little extra pass band to fight ripple / droop at the edge.
- #[arg(long)]
- pub pass_guard: Option,
- /// Use just a little extra stop band to fight ripple at the edge.
+ /// Fraction of the *target* Nyquist that is actually read (bottom half by default).
+ #[arg(long, default_value_t = 0.5, value_parser = read_fraction)]
+ pub read: f64,
+ /// This is the last filter in the chain; hold the deep pass band flat too.
#[arg(long)]
- pub stop_guard: Option,
- /// Decimation factor applied after this filter.
- #[arg(long, default_value_t = 2)]
- pub decimate: usize,
-}
-
-#[derive(Debug, clap::Args)]
-struct EstimateArgs {
- #[arg(long)]
- /// Beginning of passband as a fraction of the input sample rate
- pub passband_edge: Option,
- #[arg(long)]
- /// Width of transition band as a fraction of the input sample rate.
- pub transition_width: Option,
- #[arg(long)]
- /// How much deviation to tolerate in the passband (hint, low!)
- pub passband_ripple: Option,
- #[arg(long)]
- /// How much deviation to tolerate in the stop band (higher can be acceptable)
- pub stopband_ripple: Option,
+ pub terminal: bool,
+ /// Flat margin above the read edge, as a fraction of the read edge.
+ #[arg(long, default_value_t = 0.10, value_parser = guard_fraction)]
+ pub guard: f64,
}
fn main() -> Result<(), PmrError> {
@@ -123,13 +143,12 @@ fn main() -> Result<(), PmrError> {
match args.command {
None => unreachable!(),
Some(Command::Lowpass(a)) => cmd_lowpass(a),
- Some(Command::EstimateBins(a)) => cmd_estimate_taps(a),
}
Ok(())
}
-// ♻️ Copied from workbenc
+// ♻️ Copied from workbench
const INDENT: usize = 2;
const LABEL_W: usize = 32; // includes colon
const VALUE_W: usize = 22;
@@ -143,102 +162,74 @@ macro_rules! header {
}};
}
-fn cmd_estimate_taps(args: EstimateArgs) {
- header!("Ichige PMR Length Estimator");
- println!("Output the number of taps needed.\n\n");
- println!("Frequencies are normalized to sample rate.\n");
-
- let f_n = 1.0 / 2.0;
-
- // XXX check docs and implement things
- let fc = 0.250 * f_n;
- let fs = 0.750 * f_n;
-
- println!("cutoff band: 0.0-{}", fc);
- println!("transition width: {}", fs - fc);
- println!("stop band: {}-1.0", fs);
-
- let pass_ripple = args.passband_ripple.unwrap_or(0.001);
- let stop_ripple = args.stopband_ripple.unwrap_or(0.05);
-
- // https://docs.rs/pm-remez/latest/pm_remez/order_estimates/fn.ichige.html
- let n_taps = ichige(fc, fs - fc, pass_ripple, stop_ripple);
- println!("Estimated taps: {}", n_taps);
-}
-
fn cmd_lowpass(args: LowpassArgs) {
header!("Optimal Lowpass FIR Weights:");
let taps = args.taps.unwrap_or(21);
assert!(taps % 2 == 1, "--taps must be odd");
println!("Filter length: {taps}");
- println!("Band frequencies are normalized to sample rate of 1.0\n");
+ let d = args.decimate as f64;
+ let f_out = 1.0 / d;
+ let f_n_out = 0.5 * f_out;
+ let pass = args.read * f_n_out;
+
+ // Raw transition is everything besides pass band and its reflection.
+ let raw_transition = f_out - (2.0 * pass);
+ let guard = args.guard;
+ let pass_edge = pass * (1.0 + guard);
+ let stop_edge = f_out - pass_edge;
+
+ let guard_ratio = pass_edge / pass;
+ let read_low = pass * 0.5;
+ let deep_edge = read_low / guard_ratio;
+
+ println!("decimation: {}x", args.decimate);
+ println!("output rate: {f_out:.4} (target Nyquist {f_n_out:.4})");
+
+ println!("\nAll fractions in cycles/sample of the input rate (Nyquist = 0.5).");
+ println!("passband: 0.0-{pass:.4} (guarded through {pass_edge:.4})");
+ println!("shoulder: {pass_edge:.4}-{f_n_out:.4} (lands in unread band)");
+ println!("fold: {f_n_out:.4}-{stop_edge:.4} (folds into unread band)");
+ println!("stopband: {stop_edge:.4}-0.5 (folds into passband)");
+ println!("transition: {:.4} wide", stop_edge - pass_edge);
+ println!(
+ "weighting: {}",
+ if args.terminal {
+ "terminal (flat down to DC)"
+ } else {
+ "non-terminal (DC ripple relaxed)"
+ }
+ );
- let pass = args.pass.unwrap_or(0.125);
- let stop = args.stop.unwrap_or(0.375);
+ // NOTE my memory could be failing me, but in at least one library, I found that linear weights
+ // were implemented correctly while some constant weights were not. "Failures of imagination."
- let transition = stop - pass;
- assert!(pass < 0.5, "Pass band must end below input Nyquist");
- assert!(stop < 0.5, "Stop band must end below input Nyquist");
- assert!(transition > 0.0, "--pass must be below --stop");
+ // Below the next stage's Nyquist. Read at a lower rate downstream, so ripple
+ // here is someone else's problem. Empty when terminal.
+ let deep_pass_weight = if args.terminal { 100.0 } else { 1.0 };
+ let deep_pass =
+ BandSetting::with_weight(0.0, deep_edge, constant(1.0), constant(deep_pass_weight))
+ .unwrap();
- let pass_guard = args.pass_guard.unwrap_or(0.02);
- let stop_guard = args.stop_guard.unwrap_or(0.02);
- assert!(
- (0.0..0.5).contains(&pass_guard),
- "--pass-guard must be in [0, 0.5)"
- );
- assert!(
- (0.0..0.5).contains(&stop_guard),
- "--stop-guard must be in [0, 0.5)"
- );
+ // The read band plus guards on both sides. Flat weight, flat target.
+ let pass_band =
+ BandSetting::with_weight(deep_edge, pass_edge, constant(1.0), linear(100.0, 100.0))
+ .unwrap();
- let pass_edge = pass + transition * pass_guard;
- let stop_edge = stop - transition * stop_guard;
- assert!(
- pass_edge < stop_edge,
- "guards consumed the entire transition band"
- );
+ // Junk that stays put in a band we never read. Weakly constrained to allow ripple to flourish.
+ let shoulder =
+ BandSetting::with_weight(pass_edge, f_n_out, linear(1.0, 0.0), linear(0.00, 1.0)).unwrap();
- println!("passband: 0.0-{pass:.4} (guarded to {pass_edge:.4})");
- println!("stopband: {stop:.4}-0.5 (guarded from {stop_edge:.4})");
- println!(
- "transition: {:.4} wide, {:.4} after guards",
- transition,
- stop_edge - pass_edge
- );
+ // Junk that folds down onto the shoulder.
+ let fold =
+ BandSetting::with_weight(f_n_out, stop_edge, constant(0.0), linear(1.0, 1.0)).unwrap();
- let mid = (pass + stop) / 2.0;
- let nyquist_input = 0.5;
+ // Everything past here folds into what we read. Content near 0.5 folds to near
+ // DC, so the weight stays high across the whole band.
+ let stop_band =
+ BandSetting::with_weight(stop_edge, 0.5, constant(0.0), linear(10000.0, 10000.0)).unwrap();
- // Strongly weighted pass band.
- let pass_band =
- BandSetting::with_weight(0.0, pass_edge, constant(1.0), linear(10.0, 100.0)).unwrap();
-
- // Center band with weak weights to give solver a place we don't care about to to cram in all
- // the ripple. Less signal in transition is better, but we care more about flatness in the pass
- // and stop bands.
- let linear_transition = BandSetting::with_weight(
- // begin definition between
- pass_edge,
- stop_edge,
- constant(0.0),
- linear(0.1, 100.0),
- )
- .unwrap();
-
- // Strongly weighted stop band, favoring the deep folding region that will map directly into the
- // useful region.
- let stop_band = BandSetting::with_weight(
- stop_edge,
- nyquist_input,
- constant(0.0),
- linear(100.0, 400.0),
- )
- .unwrap();
-
- // early_transition, late_transition,
- let bands = [pass_band, stop_band]; // early_transition, late_transition,
+ let bands = [deep_pass, pass_band, shoulder, fold, stop_band];
let mut parameters = pm_parameters(taps, &bands).unwrap();
// rarely exceeds 6 or so.
@@ -246,7 +237,8 @@ fn cmd_lowpass(args: LowpassArgs) {
// We always use odd symmetry. Even symmetry is for some other use case according to pm_remez
// docs.
// parameters.set_symmetry(Symmetry::Even);
- parameters.set_flatness_threshold(0.0001);
+ parameters.set_flatness_threshold(1e-8);
+ // NOTE Setting this generally made filters worse.
// Use Chebyshev degree N = L - 1 where L is filter length and L - 1 is filter order, N.
// parameters.set_chebyshev_proxy_degree((taps - 1).min(126));
@@ -259,23 +251,18 @@ fn cmd_lowpass(args: LowpassArgs) {
// Test the max gain at various frequencies of interest.
let f_sample = 48_000f64;
- let f_pass_deep = 0.5 * pass * f_sample;
- let f_pass = pass * f_sample;
-
- let decimate = args.decimate;
- assert!(decimate >= 2, "--decimate must be at least 2");
- let d = decimate as f64;
- // Down-sampled Nyquist, the frequency at which we must see at least -6dB attenuation.
- let f_n_down = 0.5 / d * f_sample;
+ let f_pass = pass * f_sample;
+ let f_pass_deep = 0.5 * pass * f_sample;
// Source frequency whose first image lands exactly on the pass band edge.
// Content here folds *directly* into the band we still care about.
- let f_pass_mirror = (1.0 / d - pass) * f_sample;
+ let f_pass_mirror = (f_out - pass) * f_sample;
// Source frequency whose image lands on the deep pass edge. Worst case.
- let f_pass_deep_mirror = (1.0 / d - 0.5 * pass) * f_sample;
-
- let f_stop = stop * f_sample;
- let f_stop_deep = ((0.5 - stop) * 0.5 + stop) * f_sample;
+ let f_pass_deep_mirror = (f_out - 0.5 * pass) * f_sample;
+ // Down-sampled Nyquist, the frequency at which we must see at least -6dB attenuation.
+ let f_n_down = f_n_out * f_sample;
+ let f_stop = stop_edge * f_sample;
+ let f_stop_deep = ((0.5 - stop_edge) * 0.5 + stop_edge) * f_sample;
let mut input = SineSweeper::new(777.0, f_sample as f64);
// NOTE normalization seems to violate some of the ideas behind the theory.
@@ -285,7 +272,7 @@ fn cmd_lowpass(args: LowpassArgs) {
let coefficients_f32: Vec = coefficients.iter().map(|&c| c as f32).collect();
let mut filter = DynamicFirLowpass::with_coefficients(coefficients_f32.clone());
- // Is there a band named pass? 🚿
+ // Is there a band named Pass? 🚿
header!("Gain Testing");
for (f_test, band_name) in [
(f_pass_deep, "deep pass band"),
@@ -301,13 +288,22 @@ fn cmd_lowpass(args: LowpassArgs) {
for _ in 0..warmup {
filter.process(input.next().unwrap());
}
- let measure = input.nsamples(512.0);
- let mut peak: f32 = 0.0;
+
+ let measure = input.nsamples(256.0);
+ // Ratio of RMS, so the input's own partial-cycle bias mostly cancels and we don't
+ // care what amplitude SineSweeper hands us.
+ let mut energy_in = 0.0f64;
+ let mut energy_out = 0.0f64;
for _ in 0..measure {
- peak = peak.max(filter.process(input.next().unwrap()).abs());
+ let x = input.next().unwrap();
+ let y = filter.process(x);
+ energy_in += (x as f64) * (x as f64);
+ energy_out += (y as f64) * (y as f64);
}
+ let gain = (energy_out / energy_in).sqrt();
+ let db = 20.0 * gain.log10();
- println!(" {:<42} {peak:2.8}", format!("{band_name}:"));
+ println!(" {:<42} {gain:.8} {db:+8.2} dB", format!("{band_name}:"));
}
header!("64-bit Weights");
@@ -319,7 +315,6 @@ fn cmd_lowpass(args: LowpassArgs) {
}
println!("];");
- // XXX filter truncating!
header!("32-bit Weights");
println!("const FILTER: [f32; {taps}] = [");
for w in &coefficients_f32 {
@@ -328,6 +323,4 @@ fn cmd_lowpass(args: LowpassArgs) {
println!(" f32::from_bits(0x{bits:08x}), // {w:+.9e}");
}
println!("];");
-
- // XXX Test the frequency folding with the new weights :-)
}
diff --git a/mutate-lib/src/dsp/bank.rs b/mutate-lib/src/dsp/bank.rs
index e89d8439..9a9714b3 100644
--- a/mutate-lib/src/dsp/bank.rs
+++ b/mutate-lib/src/dsp/bank.rs
@@ -3,12 +3,15 @@
//! # Bank
//!
-//! *A filter banks combines filters in order to comb the desert for fugitives and their stolen
-//! robots.*
+//! > Get to the chopper!
+//! >
+//! > Jean Claude Van Damme
//!
-//! Certain design goals will always pull us towards multiple sub-banks and multiple output time
-//! slots. This module contains the data structures necessary to describe our bank so that it may
-//! be hardcoded into GPU control logic for execution.
+//! Chop up spectrum into bins. Tell us important facts about each bin.
+//!
+//! When designing a filter bank, the geometry of the bins is usually selected first and then
+//! filters are chosen to fit the bank. This module is focused on the geometry part, deciding where
+//! bin boundaries will be.
use super::iso226;
@@ -48,41 +51,40 @@ pub fn bins(min: f64, max: f64, count: usize) -> Vec {
// yet digested the coffee. ☕
//
// The sum of logs is the log of a product. The product of all of the factors for all steps is
- // equal to max / min. We are chopping up a ratio into equal ratios rather than chopping up a
- // sum into equal summands.
+ // equal to `max / min`. We are chopping up a ratio of `(max / min)` into equal ratios rather
+ // than chopping up a sum into equal summands.
//
- // The first bin and last bin are actually half-step inside. Bins must know their width, so
- // it's actually easier if we walk the log in half steps. For each bin, we will walk two half
- // steps, beginning at min and ending at max. Thus there are 2 * count steps.
+ // `min` and `max` are centers, so the walk spans count - 1 whole steps. Bins must know their
+ // width, so we walk in half steps and let the outer half steps hang outside the range.
let ratio = max / min;
- let steps = 2 * count;
+ let steps = 2 * (count - 1);
// method 1
// max_ratio: 1.0000000000000004441
let log_step = ratio.log2() / steps as f64;
- let freq = |i: usize| min * (log_step * i as f64).exp2();
+ let freq = |i: i64| min * (log_step * i as f64).exp2();
// Method 2
// max_ratio: 0.9999999999997188915
// sum of logs is log of product, and the product of steps is equal to the ratio.
// let step = (ratio.log2() / (steps as f64)).exp2();
- // let freq = |i: usize| min * step.powi(i as i32);
+ // let freq = |i: i64| min * step.powi(i as i32);
// Method 3
// max_ratio: 0.9999999999994294564
// The ith root to the ith power is unity
// let step = ratio.powf(1.0 / steps as f64); // * 0.99999989418598;
- // let freq = |i: usize| min * step.powf(i as f64);
+ // let freq = |i: i64| min * step.powf(i as f64);
// Method 2
(0..count)
.map(|i| {
- let i0 = i * 2;
- let center = freq(i0 + 1);
+ let i0 = 2 * i as i64;
+ let center = freq(i0);
Bin {
- min: freq(i0),
+ min: freq(i0 - 1),
center,
- max: freq(i0 + 2),
+ max: freq(i0 + 1),
iso226_gain: iso226::iso226_window_gain(center),
}
})
@@ -106,13 +108,12 @@ pub fn bin_lookup(min: f64, max: f64, count: usize, center: f64) -> Bin {
#[cfg(test)]
mod test {
-
use crate::dsp;
use super::*;
#[test]
- fn test_bins_range() {
+ fn bins_are_sane() {
let count = dsp::spectrogram::RESOLUTION_4K_WIDTH;
let freq_min = dsp::MIN_FREQ_CHEAP_DRIVERS;
let freq_max = dsp::MAX_FREQ_OLD_PEOPLE;
@@ -120,8 +121,8 @@ mod test {
assert_eq!(bins.len(), count);
- let min = bins[0].min;
- let max = bins.last().unwrap().max;
+ let min = bins[0].center;
+ let max = bins.last().unwrap().center;
// Check that we covered the range by verifying that our interpolation hits the same
// beginning and end points.
@@ -143,16 +144,17 @@ mod test {
assert!(b.center < b.max);
}
- // Bandwidth sum matches target spectrum
+ // Bins tile their covered span
let mut sum = 0.0;
for b in bins.iter() {
sum += b.bandwidth();
}
- assert!(((sum / (freq_max - freq_min)) - 1.0).abs() < 0.000000000000001);
+ let span = bins.last().unwrap().max - bins[0].min;
+ assert!(((sum / span) - 1.0).abs() < 0.000000000000001);
}
#[test]
- fn test_bins_bin_lookup() {
+ fn bin_lookup_is_sane() {
let target = 4000.0;
let closest = bin_lookup(
dsp::MIN_FREQ_CHEAP_DRIVERS,
@@ -161,29 +163,27 @@ mod test {
target,
);
- // NOTE bins do not have infinite resolution
-
let ratio = closest.center / target;
assert!((ratio - 1.0).abs() < 0.01);
- // First bin will have the minimum frequency
+ // First bin is centered on the minimum frequency
let closest = bin_lookup(
dsp::MIN_FREQ_CHEAP_DRIVERS,
dsp::MAX_FREQ_OLD_PEOPLE,
dsp::spectrogram::RESOLUTION_4K_WIDTH,
0.0,
);
- let ratio = closest.min / dsp::MIN_FREQ_CHEAP_DRIVERS;
+ let ratio = closest.center / dsp::MIN_FREQ_CHEAP_DRIVERS;
assert!((ratio - 1.0).abs() < 0.0000001);
- // Last bin will have the maximum frequency
+ // Last bin is centered on the maximum frequency
let closest = bin_lookup(
dsp::MIN_FREQ_CHEAP_DRIVERS,
dsp::MAX_FREQ_OLD_PEOPLE,
dsp::spectrogram::RESOLUTION_4K_WIDTH,
100_000.0,
);
- let ratio = closest.max / dsp::MAX_FREQ_OLD_PEOPLE;
+ let ratio = closest.center / dsp::MAX_FREQ_OLD_PEOPLE;
assert!((ratio - 1.0).abs() < 0.0000001);
}
}
diff --git a/mutate-lib/src/dsp/mod.rs b/mutate-lib/src/dsp/mod.rs
index 0156b1e8..99cc641f 100644
--- a/mutate-lib/src/dsp/mod.rs
+++ b/mutate-lib/src/dsp/mod.rs
@@ -67,6 +67,7 @@ pub mod fir;
pub mod iir;
pub mod iso226;
pub mod spectrogram;
+pub mod wavelet;
pub mod window;
/// Old people and rock stars cannot hear above certain frequencies. Even if the sampling rate will
diff --git a/mutate-lib/src/dsp/wavelet/calibrate.rs b/mutate-lib/src/dsp/wavelet/calibrate.rs
new file mode 100644
index 00000000..4d01f8f5
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/calibrate.rs
@@ -0,0 +1,1066 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # Calibrate
+//!
+//! Measure filter behavior versus configuration parameters. Predict [`Bin`] configurations needed
+//! to achieve goal behaviors without baking any [`Wavelet`]s.
+//!
+//! > Poca agua bendita sale de un dique reventado.
+//! >
+//! > - Ernesto Guaraná
+//!
+//! ## Motivation
+//!
+//! We want to plan filter banks. This requires control over filter behavior at each bin. However,
+//! even at a constant Q and truncation setting:
+//!
+//! - The noise floor rises with ρ (our filters are L1 normalized by default)
+//! - Wide main lobes and skirts begin to fold after the Nyquist limit, adding mirror response to at
+//! negative frequency, corrupting reassignment signal.
+//! - High truncation settings begin eating the filter body, broadening the main lobes.
+//! - Mild analytic deviations exist across γ, Q, and
+//!
+//! All of this means that the filter the user asks for can never be the filter they get without
+//! using a complete model of the related behaviors.
+//!
+//! Furthermore, modeling the critical `Q_reassign`, the effective bandwidth after including the
+//! precision of pitch reassignment, can only be derived from an accurate model of signal-to-noise
+//! ratio in response to musically relevant pitch offsets. Inaccurate, purely analytic
+//! understanding of main lobe widths and skirts would compound errors in those estimates, leading
+//! to banded response patterns where parts of the bank perform as advertised while other parts are
+//! frustrated by the local bias patterns.
+//!
+//! Finally, measuring the intended response for every single wavelet through trial-and-error would
+//! require building a [`Wavelet`] for each trial, which gets expensive fast. Both banks and tests
+//! need many wavelets. Persisting a calibrated map of the responses for a whole family of wavelets
+//! enables cheap predictions. Because each relation carries the analytic shape of what it
+//! measures, a fit is a handful of coefficients.
+//!
+//! ## Primary and Derived Quantities
+//!
+//! The tail at the cut and the Nyquist fold are analytic. PSL and main lobe width are measured and
+//! tight. Floor is the skirt read at the antipode, so it fits only the decay out from the PSL.
+//! The fold is the main lobe at Nyquist and matters only where it clears the PSL. Center stays
+//! under a cent and is held as a contract rather than predicted.
+//!
+//! Width alone knees. A shallow cut eats the main lobe in proportion to the envelope left at the
+//! cut, which is gone by x ≈ 3.5. The knee is fit in log, where it is linear, so its deep tail
+//! weighs as much as its shallow crest. PSL crosses its shoulder handoff inside its margin.
+//!
+//! ## Key Relations
+//!
+//! ```text
+//! u ρ(K − 1), realized half span in carrier periods
+//! x 2πu / P, envelope sigmas at the cut
+//! t truncation_tail(u)
+//! R 20 log10(Q/ρ), twice the main lobe widths out to the antipode
+//!
+//! psl = t (1 + p_slope/P) + p_0 + ρ (p_rho + p_lobe/Q)
+//! floor = psl + f_0 + f_tail t − f_reach R
+//! fold = image_db(ρ)
+//! width·Q = 1 + w_knee xⁿ e^{−m x²/2}
+//! Q_real = Q / width·Q
+//! ```
+//!
+//! Predictions are envelopes. Levels rise by a margin and the knee scales by one, each covering
+//! `ENVELOPE` of measured bins, so plans over deliver rather than miss. Levels on table rounding
+//! and cells whose fold breaks the shallowest plan stay out of the fits.
+//!
+//! Predictions exist only at realized halves. Measurement records every half at unit quantum, so
+//! each fit point carries just the taps its length needs. A plan takes the least half on its
+//! quantum whose envelope holds, and taps rounding adds past that only deepen what it delivers.
+
+// 🤖 Mostly generated so far. Working on the user API. Keep it working, but don't worry about
+// stepping on anyone's pet lines of code.
+
+use core::f64::consts::{PI, TAU};
+
+use super::inspect::{bisect, characterize, db, skirts, Inspect, OVERSAMPLE};
+use super::spec::Shape;
+use super::{refine, restrict, Bin, WaveletSpec};
+
+/// Lowest delivered Q. Shorter filters have a main lobe too wide to place a pitch.
+pub const Q_REAL_MIN: f64 = 1.0;
+/// Deepest floor a plan promises.
+pub const DEEPEST_DB: f64 = -120.0;
+/// Shallowest floor a plan targets. Cells whose fold breaks it are never planned.
+const SHALLOWEST_DB: f64 = -40.0;
+/// Levels on f32 table rounding, where they plateau whatever the cut.
+const QUANTIZED_DB: f64 = -135.0;
+/// Share of measured bins each envelope covers.
+const ENVELOPE: f64 = 0.9;
+/// Knee excess the width fit and its envelope resolve, clear of bulk offsets.
+const KNEE_GATE: f64 = 0.02;
+
+/// Everything shaping a bake besides Q and its maxima.
+#[derive(Clone, Copy)]
+pub struct Settings {
+ pub gamma: f64,
+ pub resolution: usize,
+ pub restriction: restrict::Restriction,
+ pub refinement: Option,
+}
+
+impl Default for Settings {
+ fn default() -> Self {
+ let s = WaveletSpec::default();
+ Settings {
+ gamma: s.shape.gamma,
+ resolution: s.resolution,
+ restriction: s.restriction,
+ refinement: s.refinement,
+ }
+ }
+}
+
+impl Settings {
+ /// Default restriction and refinement at γ 3.
+ pub fn knee() -> Self {
+ Settings {
+ gamma: 3.0,
+ ..Settings::default()
+ }
+ }
+
+ pub fn shape(&self, q: f64) -> Shape {
+ Shape::from_q(q, self.gamma)
+ }
+
+ /// A family at `q`, maxima left to the caller.
+ pub fn wavelet(&self, q: f64) -> WaveletSpec {
+ WaveletSpec::default()
+ .shape(self.shape(q))
+ .resolution(self.resolution)
+ .restriction(self.restriction)
+ .refinement(self.refinement)
+ }
+}
+
+/// Grid a calibration measures.
+#[derive(Clone, Copy)]
+pub struct Sweep {
+ pub qs: &'static [f64],
+ pub rhos: &'static [f64],
+ /// (lo, hi, step) of x
+ pub xs: (f64, f64, f64),
+}
+
+impl Default for Sweep {
+ fn default() -> Self {
+ Sweep {
+ qs: &[3.5, 6.0, 12.0, 20.0],
+ rhos: &[0.05, 0.15, 0.2, 0.25, 0.3, 0.4],
+ xs: (2.0, 5.25, 0.1),
+ }
+ }
+}
+
+/// Lifts from each fitted relation to the envelope `ENVELOPE` of measured bins sit under.
+#[derive(Clone, Copy, Debug)]
+pub struct Margin {
+ /// dB
+ pub psl: f64,
+ /// dB
+ pub floor: f64,
+ /// dB over the analytic fold
+ pub fold: f64,
+ /// Scale on the width knee
+ pub knee: f64,
+}
+
+impl Margin {
+ /// The fitted relations themselves.
+ const NONE: Margin = Margin {
+ psl: 0.0,
+ floor: 0.0,
+ fold: 0.0,
+ knee: 1.0,
+ };
+}
+
+/// Skirt level re the PSL at fπ from the crest.
+///
+/// ```text
+/// L − psl = base + tail t − reach R(f)
+/// ```
+#[derive(Clone, Copy, Debug)]
+pub struct Decay {
+ pub base: f64,
+ /// Clear lost per dB of cut
+ pub tail: f64,
+ /// |H| ∝ d^{−reach}
+ pub reach: f64,
+}
+
+impl Decay {
+ fn at(&self, psl: f64, tail: f64, q: f64, rho: f64, f: f64) -> f64 {
+ psl + self.base + self.tail * tail - self.reach * reach_db(q, rho, f)
+ }
+
+ /// Fit over (obs, L, f).
+ fn fit<'a>(rows: impl Iterator- ) -> Self {
+ let rows: Vec<_> = rows
+ .map(|(o, level, f)| ([1.0, o.tail, -reach_db(o.q, o.rho, f)], level - o.psl))
+ .collect();
+ let [base, tail, reach] = lstsq(&rows);
+ Decay { base, tail, reach }
+ }
+}
+
+/// Coefficients of the module's relations.
+#[derive(Clone, Copy, Debug)]
+pub struct Fit {
+ pub p_0: f64,
+ /// Tail slope excess in units of 1/P
+ pub p_slope: f64,
+ pub p_rho: f64,
+ pub p_lobe: f64,
+ /// Skirt at the antipode
+ pub floor: Decay,
+ pub w_knee: f64,
+ pub w_n: f64,
+ pub w_m: f64,
+ /// x the fit was measured over.
+ pub span: (f64, f64),
+ pub margin: Margin,
+}
+
+impl Fit {
+ /// Priors. Rectangular Gibbs lobe under the tail, C¹ skirt from a lobe 2.7 widths out,
+ /// Gaussian edge knee.
+ pub const ANALYTIC: Fit = Fit {
+ p_0: -13.26,
+ p_slope: 0.0,
+ p_rho: 0.0,
+ p_lobe: 0.0,
+ floor: Decay {
+ base: 29.3,
+ tail: 0.0,
+ reach: 2.0,
+ },
+ w_knee: 0.7,
+ w_n: 2.0,
+ w_m: 1.0,
+ span: (1.7, 5.25),
+ margin: Margin {
+ psl: 3.0,
+ floor: 10.0,
+ fold: 3.0,
+ knee: 1.2,
+ },
+ };
+
+ /// Knee settings, printed by `calibration_is_fit` once accepted.
+ pub const CALIBRATED: Fit = Fit {
+ p_0: -13.07015008941905,
+ p_slope: -0.5883677857968512,
+ p_rho: 2.548070102227145,
+ p_lobe: 9.0243837366645,
+ floor: Decay {
+ base: 37.24895110631419,
+ tail: -0.12981152500147797,
+ reach: 2.6614525619662492,
+ },
+ w_knee: 1.033828933140709,
+ w_n: 1.1611723927192519,
+ w_m: 0.8620850505812259,
+ span: (2.009355381156725, 5.498437260308141),
+ margin: Margin {
+ psl: 2.641687032523194,
+ floor: 2.298835040603791,
+ fold: 3.6338203145165835,
+ knee: 1.0400243351581635,
+ },
+ };
+
+ /// Relations fit to `obs` at `gamma`, each independently of the others.
+ pub(super) fn new(gamma: f64, obs: &[Obs]) -> Self {
+ let lobed: Vec<&Obs> = obs.iter().filter(|o| resolved(o.psl)).collect();
+
+ // psl − t
+ let rows: Vec<_> = lobed
+ .iter()
+ .map(|o| {
+ let p = Shape::from_q(o.q, gamma).p();
+ ([o.tail / p, 1.0, o.rho, o.rho / o.q], o.psl - o.tail)
+ })
+ .collect();
+ let [p_slope, p_0, p_rho, p_lobe] = lstsq(&rows);
+
+ let floor = Decay::fit(
+ lobed
+ .iter()
+ .filter(|o| resolved(o.floor))
+ .map(|o| (*o, o.floor, 1.0)),
+ );
+
+ // ln(width·Q − 1) = ln w_knee + n ln x − m x²/2
+ let rows: Vec<_> = obs
+ .iter()
+ .filter(|o| o.width_q - 1.0 >= KNEE_GATE)
+ .map(|o| ([1.0, o.x.ln(), -0.5 * o.x * o.x], (o.width_q - 1.0).ln()))
+ .collect();
+ let [ln_w, w_n, w_m] = lstsq(&rows);
+
+ let xs = obs.iter().map(|o| o.x);
+ let span = (
+ xs.clone().fold(f64::INFINITY, f64::min),
+ xs.fold(f64::NEG_INFINITY, f64::max),
+ );
+
+ let fit = Fit {
+ p_0,
+ p_slope,
+ p_rho,
+ p_lobe,
+ floor,
+ w_knee: ln_w.exp(),
+ w_n,
+ w_m,
+ span,
+ margin: Margin::NONE,
+ };
+ Fit {
+ margin: fit.margin_over(gamma, obs),
+ ..fit
+ }
+ }
+
+ /// Envelope at `shape` and `rho` with `half` folded weights past the center.
+ pub fn predict(&self, shape: Shape, rho: f64, half: usize) -> Prediction {
+ let (q, p) = (shape.q(), shape.p());
+ let u = rho * (half + 1) as f64;
+ let (tail, x) = (shape.truncation_tail(u), TAU * u / p);
+ let m = self.margin;
+
+ let psl = tail * (1.0 + self.p_slope / p) + self.p_0 + rho * (self.p_rho + self.p_lobe / q);
+ let floor = self.floor.at(psl, tail, q, rho, 1.0);
+
+ Prediction {
+ q,
+ rho,
+ half,
+ u,
+ x,
+ tail,
+ psl: psl + m.psl,
+ floor: floor + m.floor,
+ fold: shape.image_db(rho) + m.fold,
+ width_q: 1.0 + m.knee * self.w_knee * knee(x, self.w_n, self.w_m),
+ }
+ }
+
+ /// Margins lifting these relations over `ENVELOPE` of `obs`.
+ fn margin_over(&self, gamma: f64, obs: &[Obs]) -> Margin {
+ let pairs: Vec<(&Obs, Prediction)> = obs
+ .iter()
+ .map(|o| {
+ (
+ o,
+ self.predict(Shape::from_q(o.q, gamma), o.rho, o.taps / 2),
+ )
+ })
+ .collect();
+
+ // q_ENVELOPE of seen − fit over resolved levels
+ let lift = |seen: fn(&Obs) -> f64, fit: fn(&Prediction) -> f64| {
+ let v = pairs
+ .iter()
+ .filter(|(o, _)| resolved(seen(o)))
+ .map(|(o, p)| seen(o) - fit(p))
+ .collect();
+ quantile(v, ENVELOPE)
+ };
+
+ // q_ENVELOPE of seen − analytic fold where the main lobe clears the PSL at Nyquist
+ let fold = pairs
+ .iter()
+ .filter(|(o, p)| resolved(o.fold) && p.fold > o.psl)
+ .map(|(o, p)| o.fold - p.fold)
+ .collect();
+
+ // q_ENVELOPE of seen over fitted knee excess where the measured knee resolves
+ let knee = pairs
+ .iter()
+ .filter(|(o, _)| o.width_q - 1.0 >= KNEE_GATE)
+ .map(|(o, p)| (o.width_q - 1.0) / (p.width_q - 1.0))
+ .collect();
+
+ Margin {
+ psl: lift(|o| o.psl, |p| p.psl),
+ floor: lift(|o| o.floor, |p| p.floor),
+ fold: quantile(fold, ENVELOPE),
+ knee: quantile(knee, ENVELOPE),
+ }
+ }
+
+ /// Tail whose PSL envelope lands on `psl` at `rho`.
+ ///
+ /// ```text
+ /// t = (psl − m_psl − p_0 − ρ(p_rho + p_lobe/Q)) / (1 + p_slope/P)
+ /// ```
+ pub fn tail_for_psl(&self, shape: Shape, rho: f64, psl: f64) -> f64 {
+ let (q, p) = (shape.q(), shape.p());
+ (psl - self.margin.psl - self.p_0 - rho * (self.p_rho + self.p_lobe / q))
+ / (1.0 + self.p_slope / p)
+ }
+}
+
+/// Response a calibration promises at a realized length. Levels in dB re the crest, each an
+/// envelope.
+#[derive(Clone, Copy, Debug)]
+pub struct Prediction {
+ pub q: f64,
+ pub rho: f64,
+ /// Folded weights past the center.
+ pub half: usize,
+ /// ρ half
+ pub u: f64,
+ pub x: f64,
+ /// Feeds `with_truncation`.
+ pub tail: f64,
+ pub psl: f64,
+ pub floor: f64,
+ /// Main lobe at Nyquist
+ pub fold: f64,
+ pub width_q: f64,
+}
+
+impl Prediction {
+ /// Q / width·Q
+ pub fn q_real(&self) -> f64 {
+ self.q / self.width_q
+ }
+}
+
+#[derive(Clone, Copy)]
+pub struct Calibration {
+ pub settings: Settings,
+ pub fit: Fit,
+}
+
+impl Calibration {
+ /// Measure `sweep` under `settings` and fit.
+ pub fn new(settings: Settings, sweep: Sweep) -> Self {
+ let obs = measure(settings, sweep);
+ Calibration {
+ settings,
+ fit: Fit::new(settings.gamma, &obs),
+ }
+ }
+
+ pub fn calibrated() -> Self {
+ Calibration {
+ settings: Settings::knee(),
+ fit: Fit::CALIBRATED,
+ }
+ }
+
+ /// Envelope at `q` and `rho` with `half` folded weights past the center.
+ pub fn predict(&self, q: f64, rho: f64, half: usize) -> Prediction {
+ self.fit.predict(self.settings.shape(q), rho, half)
+ }
+
+ /// Least half on `quantum` whose floor envelope holds `floor`, absent past `DEEPEST_DB`.
+ pub fn half_for_floor(&self, q: f64, rho: f64, floor: f64, quantum: usize) -> Option {
+ self.least_half(q, rho, quantum, floor, |p| p.floor)
+ }
+
+ /// Least half on `quantum` whose PSL envelope holds `psl`, absent past `DEEPEST_DB`.
+ pub fn half_for_psl(&self, q: f64, rho: f64, psl: f64, quantum: usize) -> Option {
+ self.least_half(q, rho, quantum, psl, |p| p.psl)
+ }
+
+ /// Least half on `quantum` whose `level` envelope holds `level_db`.
+ fn least_half(
+ &self,
+ q: f64,
+ rho: f64,
+ quantum: usize,
+ level_db: f64,
+ level: fn(&Prediction) -> f64,
+ ) -> Option {
+ let goal = -level_db.abs();
+ if goal < DEEPEST_DB {
+ return None;
+ }
+ let (lo, hi) = self.reach(q, rho, quantum)?;
+ least(
+ |n| level(&self.predict(q, rho, n * quantum)) <= goal,
+ lo,
+ hi,
+ )
+ .map(|n| n * quantum)
+ }
+
+ /// Envelope of a realized bin baked under these settings.
+ pub fn predict_bin(&self, bin: Bin<'_>) -> Prediction {
+ self.predict(bin.wavelet.shape.q(), bin.rho(), bin.len_folded() - 1)
+ }
+
+ /// Multiples of `quantum` whose halves the fit measured and whose Q_real holds `Q_REAL_MIN`.
+ fn reach(&self, q: f64, rho: f64, quantum: usize) -> Option<(usize, usize)> {
+ // (x P / 2πρ − 1) / quantum, the halves of K spanning x
+ let scale = self.settings.shape(q).p() / (TAU * rho);
+ let multiple = |x: f64| (x * scale - 1.0) / quantum as f64;
+ let (lo, hi) = (
+ multiple(self.fit.span.0).ceil() as usize,
+ multiple(self.fit.span.1).floor() as usize,
+ );
+ let lo = least(
+ |n| self.predict(q, rho, n * quantum).q_real() >= Q_REAL_MIN,
+ lo,
+ hi,
+ )?;
+ Some((lo, hi))
+ }
+
+ /// Q at least `q` whose fold envelope holds `floor` at `rho`, at the least half on `quantum`
+ /// holding it past the fold.
+ pub fn plan(&self, q: f64, rho: f64, floor: f64, quantum: usize) -> Option {
+ // goal − fold margin
+ let limit = -floor.abs() - self.fit.margin.fold;
+ let fold = self.settings.shape(q).image_db(rho);
+ // fold ∝ β ∝ Q²
+ let q = match fold > limit {
+ true => q * (limit / fold).sqrt(),
+ false => q,
+ };
+ self.half_for_floor(q, rho, floor, quantum)
+ .map(|half| self.predict(q, rho, half))
+ }
+}
+
+/// One realized bin as delivered. Levels in dB re the crest, center in cents.
+#[derive(Clone, Copy)]
+pub(super) struct Obs {
+ pub q: f64,
+ pub rho: f64,
+ pub u: f64,
+ pub x: f64,
+ pub taps: usize,
+ pub tail: f64,
+ pub psl: f64,
+ pub floor: f64,
+ pub fold: f64,
+ pub width_q: f64,
+ pub center: f64,
+}
+
+/// Absent where the bin has no crest or delivers Q under `Q_REAL_MIN`.
+pub(super) fn observe(bin: Bin<'_>) -> Option {
+ let shape = bin.wavelet.shape;
+ let (q, rho, w0) = (shape.q(), bin.rho(), bin.velocity());
+ let u = rho * bin.len_folded() as f64;
+ let wts = bin.weights();
+ let psi = wts.psi();
+
+ let mut buf = Vec::new();
+ Inspect::new(psi, &mut buf, OVERSAMPLE).peak(w0, 0.0, PI)?;
+ let r = characterize(psi, w0);
+ // Q_real = 1 / rel_width
+ if r.rel_width * Q_REAL_MIN > 1.0 {
+ return None;
+ }
+ let rel = |v: f64| db(v) - db(r.gain);
+
+ let (lo, hi) = skirts(psi, &r);
+ let psl = [lo.peak, hi.peak]
+ .into_iter()
+ .flatten()
+ .map(|(_, h)| rel(h))
+ .fold(f64::NAN, f64::max);
+
+ Some(Obs {
+ q,
+ rho,
+ u,
+ x: TAU * u / shape.p(),
+ taps: bin.len_unfolded(),
+ tail: shape.truncation_tail(u),
+ psl,
+ floor: rel(r.floor),
+ fold: rel(psi.dtft(PI).abs()),
+ width_q: r.rel_width * q,
+ center: 1200.0 * (r.peak_w / w0).log2(),
+ })
+}
+
+/// Level above table rounding, false where absent.
+fn resolved(level: f64) -> bool {
+ level > QUANTIZED_DB
+}
+
+/// 20 log10(fQ/ρ), twice the main lobe widths out to fπ from the crest
+fn reach_db(q: f64, rho: f64, f: f64) -> f64 {
+ 20.0 * (f * q / rho).log10()
+}
+
+/// xⁿ e^{−m x²/2}
+fn knee(x: f64, n: f64, m: f64) -> f64 {
+ x.powf(n) * (-0.5 * m * x * x).exp()
+}
+
+/// Every distinct realized bin of `sweep` at unit quantum, starting a step inside the taper's
+/// domain, over cells whose fold holds the shallowest plan.
+pub(super) fn measure(settings: Settings, sweep: Sweep) -> Vec {
+ let (lo, hi, step) = sweep.xs;
+ let xs: Vec =
+ grid((lo.max(settings.restriction.taper.x_min() + step), hi, step)).collect();
+ let deepest = xs.iter().copied().fold(f64::NEG_INFINITY, f64::max);
+ let mut out = Vec::new();
+
+ for &q in sweep.qs {
+ let shape = settings.shape(q);
+ // u = x P / 2π
+ let u = |x: f64| x * shape.p() / TAU;
+ let wav = settings
+ .wavelet(q)
+ .max_load_quantum(1)
+ .max_half_span(u(deepest))
+ .bake();
+
+ for &rho in sweep.rhos {
+ if shape.image_db(rho) > SHALLOWEST_DB {
+ continue;
+ }
+ let mut last = 0;
+ for &x in &xs {
+ let half = (u(x) / rho).ceil() as usize - 1;
+ if half != last {
+ last = half;
+ out.extend(observe(wav.at_reach(rho, half)));
+ }
+ }
+ }
+ }
+ out
+}
+
+/// Value under which share `f` of `v` falls, NaN over nothing.
+fn quantile(mut v: Vec, f: f64) -> f64 {
+ if v.is_empty() {
+ return f64::NAN;
+ }
+ v.sort_by(f64::total_cmp);
+ v[((v.len() - 1) as f64 * f).round() as usize]
+}
+
+/// lo + i·step up to hi.
+fn grid((lo, hi, step): (f64, f64, f64)) -> impl Iterator
- + Clone {
+ let n = ((hi - lo) / step + 1e-6).floor() as usize;
+ (0..=n).map(move |i| lo + step * i as f64)
+}
+
+/// Least n of [lo, hi] where a monotone `holds` turns true.
+fn least(holds: impl Fn(usize) -> bool, mut lo: usize, mut hi: usize) -> Option {
+ if lo > hi || !holds(hi) {
+ return None;
+ }
+ while lo < hi {
+ let mid = lo + (hi - lo) / 2;
+ match holds(mid) {
+ true => hi = mid,
+ false => lo = mid + 1,
+ }
+ }
+ Some(lo)
+}
+
+/// x minimizing Σ (a·x − y)².
+fn lstsq(rows: &[([f64; M], f64)]) -> [f64; M] {
+ // AᵀA x = Aᵀy
+ let (mut n, mut b) = ([[0.0; M]; M], [0.0; M]);
+ for (a, y) in rows {
+ for i in 0..M {
+ b[i] += a[i] * y;
+ for j in 0..M {
+ n[i][j] += a[i] * a[j];
+ }
+ }
+ }
+
+ // Gauss Jordan with partial pivoting
+ for c in 0..M {
+ let p = (c..M)
+ .max_by(|&i, &j| n[i][c].abs().total_cmp(&n[j][c].abs()))
+ .unwrap();
+ n.swap(c, p);
+ b.swap(c, p);
+ let (pivot, pb) = (n[c], b[c]);
+ for r in (0..M).filter(|&r| r != c) {
+ let f = n[r][c] / pivot[c];
+ for j in 0..M {
+ n[r][j] -= f * pivot[j];
+ }
+ b[r] -= f * pb;
+ }
+ }
+
+ core::array::from_fn(|i| b[i] / n[i][i])
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ // NOTE The tests have two parts:
+ //
+ // - Run a fresh calibration via `make_calibration`
+ // - Test the `Calibration::CALIBRATED` via `calibration_is_accepted`
+
+ /// (IQM |e|, median e, worst e) over rows with an error
+ fn scale(e: &[f64]) -> [f64; 3] {
+ let e: Vec = e.iter().copied().filter(|e| !e.is_nan()).collect();
+ let mut abs: Vec = e.iter().map(|e| e.abs()).collect();
+ abs.sort_by(f64::total_cmp);
+ let q = abs.len() / 4;
+ let mid = &abs[q..abs.len() - q];
+ [
+ mid.iter().sum::() / mid.len() as f64,
+ quantile(e.clone(), 0.5),
+ e.iter().copied().fold(f64::NEG_INFINITY, f64::max),
+ ]
+ }
+
+ /// Plans off the calibration ladder deliver their PSL and sit under the calibration's own
+ /// envelopes. Each realized bin answers once, and the PSL envelope answers where it chose the
+ /// length. Margins must sit under limits contaminated fits cross.
+ fn accept(cal: &Calibration) -> bool {
+ // Target margins, the over delivery each envelope costs.
+ const PSL_DB: f64 = 2.5;
+ const FLOOR_DB: f64 = 6.0;
+ const FOLD_DB: f64 = 3.0;
+ const KNEE: f64 = 1.1;
+ // Margins contaminated fits cross, well clear of the in-domain bands.
+ const PSL_CEIL_DB: f64 = 5.0;
+ const FLOOR_CEIL_DB: f64 = 12.0;
+ const FOLD_CEIL_DB: f64 = 10.0;
+ const KNEE_CEIL: f64 = 1.3;
+
+ const QUANTA: [usize; 2] = [1, 4];
+ const QS: [f64; 3] = [4.5, 8.5, 16.0];
+ const RHOS: [f64; 4] = [0.08, 0.2, 0.25, 0.35];
+ const PSLS: [f64; 4] = [-40.0, -60.0, -80.0, -100.0];
+ /// `ENVELOPE` less slack for bins off the ladder.
+ const ENVELOPED: f64 = 0.85;
+ /// Width·Q a Q_real promise ignores.
+ const WIDTH_SLACK: f64 = 2e-3;
+
+ let m = cal.fit.margin;
+ let mut accepted = true;
+
+ println!("\n=== ACCEPTANCE (γ {}) ===", cal.settings.gamma);
+ println!(
+ "\n fit measured over x {:.2} to {:.2}",
+ cal.fit.span.0, cal.fit.span.1
+ );
+ println!("\n margin is how far each envelope sits over its fitted relation");
+ println!(" target is the margin we would like, limit is where the fit is contaminated\n");
+ println!(" {:>6} {:>9} {:>9} {:>9}", "", "margin", "target", "limit");
+ for (label, v, w, c, unit) in [
+ ("psl", m.psl, PSL_DB, PSL_CEIL_DB, "dB"),
+ ("floor", m.floor, FLOOR_DB, FLOOR_CEIL_DB, "dB"),
+ ("fold", m.fold, FOLD_DB, FOLD_CEIL_DB, "dB"),
+ ("knee", m.knee, KNEE, KNEE_CEIL, "×"),
+ ] {
+ let mark = match (v < w, v < c) {
+ (true, _) => "",
+ (false, true) => "over target",
+ (false, false) => "FAIL over limit",
+ };
+ println!(
+ " {label:>6} {:>9} {:>9} {:>9} {mark}",
+ format!("{v:.2} {unit:<2}"),
+ format!("{w:.2} {unit:<2}"),
+ format!("{c:.2} {unit:<2}"),
+ );
+ accepted &= v < c;
+ }
+
+ // (label, unit, (measured − fit, envelope − measured, within the envelope))
+ let mut ledgers = [
+ ("psl", "dB", Vec::new()),
+ ("floor", "dB", Vec::new()),
+ ("fold", "dB", Vec::new()),
+ ("width", "%", Vec::new()),
+ ];
+ let bare = Fit {
+ margin: Margin::NONE,
+ ..cal.fit
+ };
+ // (measured − fit, envelope − measured, envelope holds)
+ let level = |seen: f64, fit: f64, env: f64| {
+ resolved(seen).then(|| (seen - fit, env - seen, seen <= env))
+ };
+ let (mut kept, mut plans) = (0usize, 0usize);
+
+ // (Q, ρ, half) of bins already held to their envelopes
+ let mut held = Vec::new();
+ // target − psl over plans whose PSL chose the length
+ let mut waste = Vec::new();
+
+ println!("\n plans off the ladder by PSL target, levels in dB re gain");
+ println!(" error is |measured − fit|, the fit's miss before any margin");
+ println!(" by names what set the length, the requested PSL or the fit span edge\n");
+ println!(
+ " {:>3} {:>5} {:>6} {:>6} {:>5} {:>5} {:>5} {:>8} {:>7} {:>8} {:>7} {:>7} {:>7}",
+ "n",
+ "Q",
+ "rho",
+ "target",
+ "taps",
+ "x",
+ "by",
+ "psl",
+ "error",
+ "floor",
+ "error",
+ "width·Q",
+ "error %"
+ );
+
+ for quantum in QUANTA {
+ for q in QS {
+ for rho in RHOS {
+ for target in PSLS {
+ let Some(half) = cal.half_for_psl(q, rho, target, quantum) else {
+ println!(
+ " {quantum:>3} {q:>5.1} {rho:>6.3} {target:>6.0} unreachable"
+ );
+ continue;
+ };
+ let plan = cal.predict(q, rho, half);
+ let wav = cal
+ .settings
+ .wavelet(q)
+ .max_load_quantum(1)
+ .max_half_span(plan.u)
+ .bake();
+ let bin = wav.at_reach(rho, half);
+
+ // longer than the fit span edge
+ let bound = cal
+ .reach(q, rho, quantum)
+ .is_some_and(|(lo, _)| half > lo * quantum);
+ let key = (q.to_bits(), rho.to_bits(), half);
+ let fresh = !held.contains(&key);
+ if fresh {
+ held.push(key);
+ }
+
+ plans += 1;
+ let Some(seen) = observe(bin) else {
+ println!(
+ " {quantum:>3} {q:>5.1} {rho:>6.3} {target:>6.0} degenerate"
+ );
+ continue;
+ };
+ let fit = bare.predict(cal.settings.shape(q), rho, half);
+
+ println!(
+ " {quantum:>3} {q:>5.1} {rho:>6.3} {target:>6.0} {:>5} {:>5.2} \
+ {:>5} {:>8.2} {:>7.2} {:>8.2} {:>7.2} {:>7.4} {:>7.2}",
+ seen.taps,
+ seen.x,
+ if bound { "psl" } else { "span" },
+ seen.psl,
+ (seen.psl - fit.psl).abs(),
+ seen.floor,
+ (seen.floor - fit.floor).abs(),
+ seen.width_q,
+ 100.0 * (seen.width_q / fit.width_q - 1.0).abs(),
+ );
+
+ kept += (seen.psl <= target) as usize;
+ if bound && seen.psl <= target {
+ waste.push(target - seen.psl);
+ }
+
+ if fresh {
+ let rows = [
+ level(seen.psl, fit.psl, plan.psl).filter(|_| bound),
+ level(seen.floor, fit.floor, plan.floor),
+ level(seen.fold, fit.fold, plan.fold)
+ .filter(|_| plan.fold > plan.psl),
+ // 100 (W_seen / W − 1), 100 (W_env − W_seen) / W_seen
+ Some((
+ 100.0 * (seen.width_q / fit.width_q - 1.0),
+ 100.0 * (plan.width_q - seen.width_q) / seen.width_q,
+ seen.width_q - plan.width_q <= WIDTH_SLACK,
+ )),
+ ];
+ for ((_, _, errs), row) in ledgers.iter_mut().zip(rows) {
+ errs.extend(row);
+ }
+ }
+ }
+ }
+ }
+ }
+
+ println!(
+ "\n requested PSL delivered on {kept} of {plans} plans, {:.1}%",
+ 100.0 * kept as f64 / plans as f64
+ );
+ if !waste.is_empty() {
+ println!(
+ " over delivery where the PSL set the length, median {:.1} dB, q90 {:.1} dB",
+ quantile(waste.clone(), 0.5),
+ quantile(waste, 0.9)
+ );
+ }
+ accepted &= kept as f64 >= ENVELOPED * plans as f64;
+
+ let rule = "=".repeat(90);
+ println!("\n {rule}");
+ println!(" bias is the median of measured − fit, spread is how far bins land from the fit either way");
+ println!(" headroom is envelope − measured, crossed is the share of bins where it went negative");
+ println!(" {rule}");
+ println!(
+ " {:>6} {:>5} {:>13} {:>13} {:>13} {:>8} {:>15}",
+ "", "bins", "bias", "typical ±", "90% within ±", "crossed", "worst headroom"
+ );
+ for (label, unit, errs) in &ledgers {
+ let abs: Vec = errs.iter().map(|v| v.0.abs()).collect();
+ let crossed = errs.iter().filter(|v| !v.2).count() as f64 / errs.len() as f64;
+ let worst = errs.iter().map(|v| v.1).fold(f64::INFINITY, f64::min);
+ println!(
+ " {label:>6} {:>5} {:>13} {:>13} {:>13} {:>7.1}% {:>15}",
+ errs.len(),
+ format!(
+ "{:+.2} {unit:<2}",
+ quantile(errs.iter().map(|v| v.0).collect(), 0.5)
+ ),
+ format!("{:.2} {unit:<2}", scale(&abs)[0]),
+ format!("{:.2} {unit:<2}", quantile(abs.clone(), 0.9)),
+ 100.0 * crossed,
+ format!("{worst:+.2} {unit:<2}"),
+ );
+ accepted &= crossed <= 1.0 - ENVELOPED;
+ }
+ println!(" {rule}");
+
+ accepted
+ }
+
+ /// Measure and fit the knee settings, print headroom by cell and by cut, and print the literal
+ /// to paste as `Fit::CALIBRATED` once accepted.
+ #[test]
+ #[ignore]
+ fn make_calibration() {
+ /// x band edges from the knee's domain, shallow to deep.
+ const BANDS: [f64; 6] = [1.5, 2.25, 3.0, 3.5, 4.0, 6.0];
+ const UNITS: [&str; 4] = ["dB", "dB", "dB", "%"];
+
+ let settings = Settings::knee();
+ let obs = measure(settings, Sweep::default());
+ let cal = Calibration {
+ settings,
+ fit: Fit::new(settings.gamma, &obs),
+ };
+
+ // (median, share under zero) of envelope − measured for psl, floor, fold in dB and width in % of the lobe
+ let headroom = |rows: &[Obs]| -> [(f64, f64); 4] {
+ let h: Vec<[f64; 4]> = rows
+ .iter()
+ .map(|o| {
+ let p = cal.predict(o.q, o.rho, o.taps / 2);
+ let level = |want: f64, seen: f64| match resolved(seen) {
+ true => want - seen,
+ false => f64::NAN,
+ };
+ [
+ level(p.psl, o.psl),
+ level(p.floor, o.floor),
+ match p.fold > o.psl {
+ true => level(p.fold, o.fold),
+ false => f64::NAN,
+ },
+ 100.0 * (p.width_q - o.width_q) / o.width_q,
+ ]
+ })
+ .collect();
+ core::array::from_fn(|i| {
+ let v: Vec = h.iter().map(|h| h[i]).filter(|h| h.is_finite()).collect();
+ let under = v.iter().filter(|&&h| h < 0.0).count() as f64 / v.len() as f64;
+ (quantile(v, 0.5), under)
+ })
+ };
+ let cols = |stats: [(f64, f64); 4]| {
+ stats
+ .into_iter()
+ .zip(UNITS)
+ .map(|((h, under), unit)| match h.is_finite() {
+ true => format!(
+ "{:>10} {:>7}",
+ format!("{h:+.2} {unit:<2}"),
+ format!("{:.0}%", 100.0 * under)
+ ),
+ false => format!("{:>10} {:>7}", "—", "—"),
+ })
+ .collect::>()
+ .join(" ")
+ };
+ let head = format!(
+ "{:>10} {:>7} {:>10} {:>7} {:>10} {:>7} {:>10} {:>7}",
+ "psl", "missed", "floor", "missed", "fold", "missed", "width", "missed"
+ );
+
+ println!(
+ "\n=== CALIBRATION (γ {}, quantum 1, {} bins) ===",
+ settings.gamma,
+ obs.len()
+ );
+ println!(" headroom is envelope − measured, median per group, negative means the envelope was crossed");
+ println!(" missed is the share of bins that crossed it");
+ println!(" fold only where the main lobe clears the PSL at Nyquist, dash where no bin qualifies");
+ println!(" levels under {QUANTIZED_DB:.0} dB sit on table rounding and are left out\n");
+ println!(" {:>5} {:>6} {:>5} {head}", "Q", "rho", "bins");
+ for cell in obs.chunk_by(|a, b| a.q == b.q && a.rho == b.rho) {
+ println!(
+ " {:>5.1} {:>6.3} {:>5} {}",
+ cell[0].q,
+ cell[0].rho,
+ cell.len(),
+ cols(headroom(cell))
+ );
+ }
+
+ println!("\n {:>12} {:>8} {:>5} {head}", "x band", "tail dB", "bins");
+ for w in BANDS.windows(2) {
+ let rows: Vec = obs
+ .iter()
+ .copied()
+ .filter(|o| o.x >= w[0] && o.x < w[1])
+ .collect();
+ let tail = rows.iter().map(|o| o.tail).sum::() / rows.len() as f64;
+ println!(
+ " {:>12} {tail:>8.1} {:>5} {}",
+ format!("{:.2} to {:.2}", w[0], w[1]),
+ rows.len(),
+ cols(headroom(&rows))
+ );
+ }
+ println!(
+ " {:>12} {:>8} {:>5} {}",
+ "pooled",
+ "",
+ obs.len(),
+ cols(headroom(&obs))
+ );
+
+ assert!(accept(&cal), "calibration not accepted, literal withheld");
+ println!("\n paste as Fit::CALIBRATED\n{:#?}", cal.fit);
+ }
+
+ /// The pasted calibration holds under the current settings.
+ #[test]
+ fn calibration_is_accepted() {
+ assert!(
+ accept(&Calibration::calibrated()),
+ "calibration not accepted, see crossed and worst headroom per relation"
+ );
+ }
+}
diff --git a/mutate-lib/src/dsp/wavelet/generate/contour.rs b/mutate-lib/src/dsp/wavelet/generate/contour.rs
new file mode 100644
index 00000000..05483f89
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/generate/contour.rs
@@ -0,0 +1,161 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # Deformed Contour
+//!
+//! This method is a quadrature integration that is somewhat well behaved (precision in transition
+//! region sags but isn't terrible) and serves as a 3rd opinion on the IFFT and QuadJet methods. The
+//! implementation should be compact, simple, and work at any u.
+//!
+//! Other reference methods tried included Hypergeometric Airy and the Taylor expansion, but both of
+//! those only function at small u and worst of all, lose precision in a way that provides no
+//! indication of who as wrong in any u sweep. Small u methods are like the tenth doctor. They
+//! might be right, but since all evidence is against what they say, they can't decide anything
+//! alone.
+
+// NEXT support variable precision
+// NEXT use a more similar interface as QuadJet with precision knobs.
+// NEXT add a self-precison convergence test when available.
+// NEXT Check the root selection for the saddle term. Saddles near zero and in the transition have
+// been all over the place, and quadrature is generally being used to make up for this. If the
+// saddle term is bad enough, it might affect the quadrature, and that might affect the method
+// agreement. We don't need something as sophisticated / complex as QuadJet, but we shouldn't just
+// throw away available grip on a known source of badness.
+// 🤖 Of course.
+
+use num_complex::Complex64;
+use std::f64::consts::{PI, TAU};
+
+use super::super::spec::Shape;
+use super::super::whatsleft::Accumulator;
+
+const H: f64 = 1.0 / 64.0;
+const TAU_MAX: f64 = 4.0;
+
+pub struct DeformedContourEval {
+ pub value: Complex64,
+ /// log10(Σ|terms| / |Σ terms|). Expect well under 1 here.
+ #[allow(unused)]
+ pub digits_lost: f64,
+ /// Relative change between the h and 2h double-exponential rules.
+ #[allow(unused)]
+ pub residual: f64,
+}
+
+/// # Deformed Contour Method
+///
+/// Same integral as the Airy series, on a different path, in `ζ = ω/ω_p`. `[0, ∞)` becomes
+/// `0 → ζ_s → ∞·e^{iθ}`, where `ζ_s` is the saddle of `β(ln ζ − (ζ^γ − 1)/γ) + iζt` and `θ` is
+/// the steepest-descent direction clamped into the sector where `e^{-ζ^γ}` still closes the
+/// contour at infinity. The modulus is monotone along both legs, so there is no cancellation to
+/// fight and f64 keeps ~14 digits at any `u`. No asymptotics: the integrand is exact everywhere
+/// on the path.
+///
+/// Amplitude follows Lilly's convention, `Ψ(1) = 2`.
+pub fn tap_at(shape: Shape, u: f64) -> DeformedContourEval {
+ let t = TAU * u;
+ let saddle = saddle(shape, t);
+ let dir = tail_direction(shape, saddle);
+
+ // β(ln ζ − (ζ^γ − 1)/γ) + iζt
+ let f = |w: Complex64| {
+ (shape.beta * (w.ln() - (w.powf(shape.gamma) - 1.0) / shape.gamma)
+ + Complex64::new(0.0, t) * w)
+ .exp()
+ };
+ let head = |x: f64| f(saddle * x) * saddle;
+ let tail = |s: f64| f(saddle + dir * s) * dir;
+
+ let (h0, m0) = tanh_sinh(&head, H);
+ let (h1, m1) = exp_sinh(&tail, H);
+ let (c0, _) = tanh_sinh(&head, 2.0 * H);
+ let (c1, _) = exp_sinh(&tail, 2.0 * H);
+
+ let fine = h0 + h1;
+ let coarse = c0 + c1;
+
+ DeformedContourEval {
+ value: 2.0 * fine,
+ digits_lost: ((m0 + m1) / fine.norm().max(f64::MIN_POSITIVE))
+ .log10()
+ .max(0.0),
+ residual: (fine - coarse).norm() / fine.norm().max(f64::MIN_POSITIVE),
+ }
+}
+
+/// Root of `φ'(ζ) = β(1/ζ − ζ^(γ-1)) + it`, seeded from the pure-oscillatory saddle offset by the
+/// carrier so small `t` lands on the real root instead of wandering.
+fn saddle(shape: Shape, t: f64) -> Complex64 {
+ let Shape { beta, gamma } = shape;
+ let mut w = Complex64::from_polar(
+ (t / beta).powf(1.0 / (gamma - 1.0)),
+ PI / (2.0 * (gamma - 1.0)),
+ ) + 1.0;
+
+ for _ in 0..64 {
+ let d1 = beta * (w.inv() - w.powf(gamma - 1.0)) + Complex64::new(0.0, t);
+ w -= d1 / curvature(shape, w);
+ }
+ w
+}
+
+// φ''(ζ) = −β(1/ζ² + (γ−1)ζ^(γ−2))
+fn curvature(shape: Shape, w: Complex64) -> Complex64 {
+ -shape.beta * ((w * w).inv() + (shape.gamma - 1.0) * w.powf(shape.gamma - 2.0))
+}
+
+/// Steepest descent at the saddle, oriented away from the origin, clamped inside the sector where
+/// `Re ω^γ > 0` keeps the closing arc at infinity dead.
+fn tail_direction(shape: Shape, w: Complex64) -> Complex64 {
+ let descent = 0.5 * (PI - curvature(shape, w).arg());
+ let outward = if (descent - w.arg()).cos() > 0.0 {
+ descent
+ } else {
+ descent + PI
+ };
+ let limit = 0.4 * PI / shape.gamma;
+ Complex64::from_polar(1.0, outward.clamp(-limit, limit))
+}
+
+/// tanh-sinh over the unit interval; endpoint clustering absorbs the `ω^β` branch point at 0.
+fn tanh_sinh Complex64>(g: F, h: f64) -> (Complex64, f64) {
+ let n = (TAU_MAX / h) as i32;
+ let mut re: Accumulator = Accumulator::default();
+ let mut im: Accumulator = Accumulator::default();
+ let mut mass: Accumulator = Accumulator::default();
+
+ for k in -n..=n {
+ let tau = k as f64 * h;
+ let s = 0.5 * PI * tau.sinh();
+ let x = 0.5 * (1.0 + s.tanh());
+ let w = 0.25 * PI * tau.cosh() / (s.cosh() * s.cosh());
+ let term = g(x) * w;
+ if term.is_finite() {
+ re.add(term.re);
+ im.add(term.im);
+ mass.add(term.norm());
+ }
+ }
+ (Complex64::new(re.sum(), im.sum()) * h, mass.sum() * h)
+}
+
+/// exp-sinh over `[0, ∞)` for the exponentially decaying tail leg.
+fn exp_sinh Complex64>(g: F, h: f64) -> (Complex64, f64) {
+ let n = (TAU_MAX / h) as i32;
+ let mut re: Accumulator = Accumulator::default();
+ let mut im: Accumulator = Accumulator::default();
+ let mut mass: Accumulator = Accumulator::default();
+
+ for k in -n..=n {
+ let tau = k as f64 * h;
+ let s = (0.5 * PI * tau.sinh()).exp();
+ let w = s * 0.5 * PI * tau.cosh();
+ let term = g(s) * w;
+ if term.is_finite() {
+ re.add(term.re);
+ im.add(term.im);
+ mass.add(term.norm());
+ }
+ }
+ (Complex64::new(re.sum(), im.sum()) * h, mass.sum() * h)
+}
diff --git a/mutate-lib/src/dsp/wavelet/generate/hermite.rs b/mutate-lib/src/dsp/wavelet/generate/hermite.rs
new file mode 100644
index 00000000..ab7436f3
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/generate/hermite.rs
@@ -0,0 +1,342 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # Hermite Interpolation
+//!
+//! > Control! Control!
+//! >
+//! > - Darth Jar Jar
+//!
+//! Just some basic functions developed to interpolate and integrate with curvature awareness we
+//! already have. Only intended for our usage, with rotated `dψ/du` and `resolution` describing the
+//! fineness of grid points between periods `u`.
+//!
+//! ## Motivations
+//!
+//! At first, we just needed a way to test IFFT convergence without requiring perfect grid point
+//! alignment. Since most wavelet generation methods obtain `dψ/du` trivially, this allows a lower
+//! resolution `ψ` to do the job much more cheaply. The anchors are usually already over-precise,
+//! so Hermite interpolation vs evaluating more grid points is probably a win.
+//!
+//! Of course interpolation adds error. We slapped some compensation on top to *mitigate*.
+//!
+//! ## Lexicon
+//!
+//! See parent conventions for shared definitions.
+//!
+//! | symbol | Rust | object |
+//! |---|---|---|
+//! | `s` | `s` | position along the grid, `u·resolution`, so the cell is `⌊s⌋` |
+//! | `f` | `f` | fractional position within the cell, always on `[0.0, 1.0)` |
+//! | `Δu` | `delta_u` | grid spacing in `u`, `1/resolution` |
+//! | `p₀`, `p₁` | `p0`, `p1` | the bracketing tap values |
+//! | `m₀`, `m₁` | `m0`, `m1` | the tangents at those taps, scaled into cell units by `Δu` |
+//!
+//! `m` here is a Hermite tangent and not the crate's center sample. A tangent is `2π·i·d·Δu`,
+//! the storage convention reverted before the spacing goes on.
+//!
+//! `integrate` integrates against `du`, so its result is `ψ` times periods. The same sum
+//! against `dν` is larger by `1/ρ`, which is what a consumer working in samples wants.
+
+// NEXT Some characterization of the error would be appreciated. If we ask for 1e-9 but the Hermite
+// points are 1e-5, we're losing. Only if we can avoid creating more 1e-11 points achieve 1e-9 is
+// the trade worth it, and we need control!
+// NEXT healthy dose of renaming
+// MAYBE a newtype to protect rotated from de-rotated `d` from the storage channel? Would affect all
+// users, but caller that know the storage situation would be tempted to manually derotate before
+// calling.
+
+use std::f64::consts::TAU;
+
+use num_complex::Complex64;
+
+use super::Accumulator;
+
+#[inline]
+fn two_diff(a: f64, b: f64) -> (f64, f64) {
+ let s = a - b;
+ let bv = s - a;
+ (s, (a - (s - bv)) + (-b - bv))
+}
+
+/// One-sided second differences of the cell, with the two-sum residuals folded back.
+///
+/// `a = Δ − m₀`, `b = m₁ − Δ`, `Δ = p₁ − p₀`.
+#[inline(always)]
+fn deltas(p0: f64, p1: f64, m0: f64, m1: f64) -> (f64, f64) {
+ let (delta, delta_err) = two_diff(p1, p0);
+ let (a, a_err) = two_diff(delta, m0);
+ let (b, b_err) = two_diff(m1, delta);
+ (a + (a_err + delta_err), b + (b_err - delta_err))
+}
+
+/// Hermite basis in delta form, anchored on the nearer endpoint.
+///
+/// `a` and `b` are the one-sided second differences; they are the only place cancellation
+/// occurs, and the two-sum residuals are folded back before they reach the Horner chain.
+#[inline(always)]
+pub fn hermite_1d(p0: f64, p1: f64, m0: f64, m1: f64, f: f64) -> f64 {
+ let (a, b) = deltas(p0, p1, m0, m1);
+
+ if f <= 0.5 {
+ p0 + f * (b - a).mul_add(f, 2.0 * a - b).mul_add(f, m0)
+ } else {
+ let g = 1.0 - f;
+ p1 + g * (a - b).mul_add(g, 2.0 * b - a).mul_add(g, -m1)
+ }
+}
+
+/// Cubic Hermite reconstruction from a tap and its derivative.
+///
+/// Exact slopes hold the stencil at two taps. Error is `O(Δu⁴ |ψ''''|)`.
+///
+/// `s` indexes the grid, so `s = u·resolution`, and `Δu` is the spacing the exact `u`-derivatives
+/// are scaled into.
+#[cfg(test)]
+#[inline(always)]
+pub fn resample_hermite(
+ taps: &[Complex64],
+ d: &[Complex64],
+ s: f64,
+ resolution: usize,
+) -> Complex64 {
+ let cell = s.floor();
+ let f = s - cell;
+ let i = cell as usize;
+
+ let delta_u = 1.0 / resolution as f64;
+ let m0 = tangent(d[i], delta_u);
+ let m1 = tangent(d[i + 1], delta_u);
+
+ let p0 = taps[i];
+ let p1 = taps[i + 1];
+
+ Complex64::new(
+ hermite_1d(p0.re, p1.re, m0.re, m1.re, f),
+ hermite_1d(p0.im, p1.im, m0.im, m1.im, f),
+ )
+}
+
+/// The slope across one cell. The stored channel is `−(i/2π) dψ/du`, so the quarter turn goes back on
+/// before the spacing does.
+#[inline(always)]
+fn tangent(d: Complex64, delta_u: f64) -> Complex64 {
+ Complex64::I * TAU * d * delta_u
+}
+
+/// `∫_{f₀}^{f₁} p` in cell units, accumulated term by term.
+///
+/// `p = p₀ + m₀f + (2a − b)f² + (b − a)f³`, integrated with the power differences factored,
+/// `f₁ᵏ⁺¹ − f₀ᵏ⁺¹ = h·Sₖ₊₁`.
+#[inline(always)]
+fn cell_span_1d(
+ acc: &mut Accumulator,
+ p0: f64,
+ m0: f64,
+ a: f64,
+ b: f64,
+ f0: f64,
+ f1: f64,
+ h: f64,
+) {
+ let f0_2 = f0 * f0;
+ let f1_2 = f1 * f1;
+
+ let s2 = f1 + f0;
+ let s3 = f1_2 + f1 * f0 + f0_2;
+ let s4 = s2 * (f1_2 + f0_2);
+
+ let q3 = h * s3 / 3.0;
+ let q4 = h * s4 * 0.25;
+
+ acc.add(h * p0);
+ acc.add(h * m0 * s2 * 0.5);
+ acc.add(2.0 * a * q3);
+ acc.add(-b * q3);
+ acc.add(b * q4);
+ acc.add(-a * q4);
+}
+
+#[inline(always)]
+fn cell_span(
+ real: &mut Accumulator,
+ imag: &mut Accumulator,
+ p0: Complex64,
+ p1: Complex64,
+ m0: Complex64,
+ m1: Complex64,
+ f0: f64,
+ f1: f64,
+ h: f64,
+) {
+ let (a_re, b_re) = deltas(p0.re, p1.re, m0.re, m1.re);
+ let (a_im, b_im) = deltas(p0.im, p1.im, m0.im, m1.im);
+ cell_span_1d(real, p0.re, m0.re, a_re, b_re, f0, f1, h);
+ cell_span_1d(imag, p0.im, m0.im, a_im, b_im, f0, f1, h);
+}
+
+/// A whole cell, trapezoid and cubic correction kept apart.
+#[inline(always)]
+fn whole_cell(
+ real: &mut Accumulator,
+ imag: &mut Accumulator,
+ p0: Complex64,
+ p1: Complex64,
+ m0: Complex64,
+ m1: Complex64,
+) {
+ real.add(p0.re * 0.5);
+ real.add(p1.re * 0.5);
+ real.add(m0.re / 12.0);
+ real.add(-m1.re / 12.0);
+ imag.add(p0.im * 0.5);
+ imag.add(p1.im * 0.5);
+ imag.add(m0.im / 12.0);
+ imag.add(-m1.im / 12.0);
+}
+
+/// Cells touched by `[u_beg, u_end]` and each endpoint reduced to a fraction of its cell.
+///
+/// Caller is responsible that both lie within the taps' reach, otherwise the end cell's cubic
+/// is extrapolated.
+#[inline(always)]
+fn span_cells(cells: usize, u_beg: f64, u_end: f64, du: f64) -> (usize, usize, f64, f64) {
+ let last = cells - 1;
+ let i_beg = ((u_beg / du).floor() as usize).min(last);
+ let i_end = ((u_end / du).floor() as usize).min(last);
+
+ // reduced against `u` so the fraction carries no error from the grid position
+ let f = |i: usize, u: f64| (-(i as f64)).mul_add(du, u) / du;
+
+ (i_beg, i_end, f(i_beg, u_beg), f(i_end, u_end))
+}
+
+/// `∫_{u_beg}^{u_end} p du` of the cubic Hermite reconstruction of a real channel.
+///
+/// `dp` is `dp/du` on the same grid, in plain units rather than the rotated storage convention.
+///
+/// Caller is responsible that `u_beg <= u_end` and that both lie within the taps' reach.
+pub fn integrate_1d(p: &[f64], dp: &[f64], u_beg: f64, u_end: f64, du: f64) -> f64 {
+ #[inline(always)]
+ fn span(
+ acc: &mut Accumulator,
+ p: &[f64],
+ dp: &[f64],
+ du: f64,
+ i: usize,
+ f0: f64,
+ f1: f64,
+ h: f64,
+ ) {
+ let (m0, m1) = (dp[i] * du, dp[i + 1] * du);
+ let (a, b) = deltas(p[i], p[i + 1], m0, m1);
+ cell_span_1d(acc, p[i], m0, a, b, f0, f1, h);
+ }
+
+ let (i_beg, i_end, f_beg, f_end) = span_cells(p.len() - 1, u_beg, u_end, du);
+
+ let mut acc = Accumulator::default();
+
+ if i_beg == i_end {
+ let h = (u_end - u_beg) / du;
+ span(&mut acc, p, dp, du, i_beg, f_beg, f_end, h);
+ return acc.sum() * du;
+ }
+
+ // Opening fraction.
+ span(&mut acc, p, dp, du, i_beg, f_beg, 1.0, 1.0 - f_beg);
+
+ // Whole cells, trapezoid and cubic correction kept apart.
+ for i in (i_beg + 1)..i_end {
+ acc.add(p[i] * 0.5);
+ acc.add(p[i + 1] * 0.5);
+ acc.add(dp[i] * du / 12.0);
+ acc.add(-dp[i + 1] * du / 12.0);
+ }
+
+ // Closing fraction.
+ span(&mut acc, p, dp, du, i_end, 0.0, f_end, f_end);
+
+ acc.sum() * du
+}
+
+/// Integral of the cubic Hermite reconstruction over `[u_beg, u_end]`, with `du` as the measure.
+///
+/// `rho_grid` is the tap spacing in periods, which places the endpoints in the grid. Whole cells
+/// contribute their closed form and the two end cells contribute a fraction of theirs, so the sum
+/// is the exact area under the same stencil `resample_hermite` reconstructs.
+///
+/// Caller is responsible that `u_beg <= u_end` and that both lie within the taps' reach.
+pub fn integrate(
+ taps: &[Complex64],
+ d: &[Complex64],
+ u_beg: f64,
+ u_end: f64,
+ rho_grid: f64,
+) -> Complex64 {
+ let (i_beg, i_end, f_beg, f_end) = span_cells(taps.len() - 1, u_beg, u_end, rho_grid);
+
+ let cell = |i: usize| {
+ (
+ taps[i],
+ taps[i + 1],
+ tangent(d[i], rho_grid),
+ tangent(d[i + 1], rho_grid),
+ )
+ };
+
+ let mut real = Accumulator::default();
+ let mut imag = Accumulator::default();
+
+ if i_beg == i_end {
+ let (p0, p1, m0, m1) = cell(i_beg);
+ let h = (u_end - u_beg) / rho_grid;
+ cell_span(&mut real, &mut imag, p0, p1, m0, m1, f_beg, f_end, h);
+ return Complex64::new(real.sum(), imag.sum()) * rho_grid;
+ }
+
+ // Opening fraction.
+ let (p0, p1, m0, m1) = cell(i_beg);
+ cell_span(
+ &mut real,
+ &mut imag,
+ p0,
+ p1,
+ m0,
+ m1,
+ f_beg,
+ 1.0,
+ 1.0 - f_beg,
+ );
+
+ // Whole cells.
+ for i in (i_beg + 1)..i_end {
+ let (p0, p1, m0, m1) = cell(i);
+ whole_cell(&mut real, &mut imag, p0, p1, m0, m1);
+ }
+
+ // Closing fraction.
+ let (p0, p1, m0, m1) = cell(i_end);
+ cell_span(&mut real, &mut imag, p0, p1, m0, m1, 0.0, f_end, f_end);
+
+ Complex64::new(real.sum(), imag.sum()) * rho_grid
+}
+
+/// ψ at `u` on a grid of spacing `delta_u`.
+///
+/// Caller is responsible that `u` lies within the taps' reach.
+#[inline(always)]
+pub fn eval(taps: &[Complex64], d: &[Complex64], u: f64, delta_u: f64) -> Complex64 {
+ let s = u / delta_u;
+ let cell = (s.floor() as usize).min(taps.len() - 2);
+ let f = s - cell as f64;
+
+ let m0 = tangent(d[cell], delta_u);
+ let m1 = tangent(d[cell + 1], delta_u);
+ let (p0, p1) = (taps[cell], taps[cell + 1]);
+
+ Complex64::new(
+ hermite_1d(p0.re, p1.re, m0.re, m1.re, f),
+ hermite_1d(p0.im, p1.im, m0.im, m1.im, f),
+ )
+}
diff --git a/mutate-lib/src/dsp/wavelet/generate/ifft.rs b/mutate-lib/src/dsp/wavelet/generate/ifft.rs
new file mode 100644
index 00000000..434e81dc
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/generate/ifft.rs
@@ -0,0 +1,646 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # Inverse "Fast" Fourier Transform
+//!
+//! > One does not discover new lands without consenting to lose sight, for a very long time, of the
+//! > shore.
+//! >
+//! > - Krishnan Kanthavel
+//!
+//! This is the plain Jane, the easy to trust, hard to get wrong baseline. It suffers mainly from
+//! issues that affect precision convergence at high `u`. The reference methods developed to
+//! confirm and characterize the precision and accuracy grew to replace Jane, so this poor module
+//! has been demoted behind the `validation` feature.
+//!
+//! ## Symbols and Relations
+//!
+//! See parent conventions for shared definitions.
+//!
+//! | symbol | Rust | object |
+//! |---|---|---|
+//! | `j` || bin index, one-sided, so bin `record` is the carrier |
+//! || `record` | periods plus padding periods, the transform's span in `u` | carrier periods |
+//! | `ζ` | `zeta` | `j/record`, the bin's rate in turns per `u` |
+//! | `n_fft` || transform size, `record·resolution` |
+//! | `dd` || `d²ψ/du²` under two quarter turns, the derivative of `d` |
+//! ...
+//!
+//! Bin weights are `mag`, `mag·ζ`, and `mag·ζ²`, one level of `ζ` per channel, which is the
+//! quarter turn and the `1/2π` together. `reach` bounds the largest `u` a resample can index,
+
+use core::f64::consts::{LN_2, TAU};
+
+use std::ops::Div;
+
+use super::super::spec::Shape;
+
+use num_complex::Complex64;
+use rustfft::FftPlanner;
+
+/// Grid for the IFFT generator.
+///
+/// `periods` is the reach of the returned half-taps in carrier cycles; `pad` extends the record
+/// past that reach so the periodic wrap lands in the decayed tail; `resolution` is samples per
+/// carrier cycle. Only `record` and `n_fft` are derived, so no call site recomputes them.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct IfftSettings {
+ pub periods: usize,
+ pub pad: usize,
+ pub resolution: usize,
+}
+
+impl IfftSettings {
+ /// Periods + padding periods
+ pub fn record(self) -> usize {
+ self.periods + self.pad
+ }
+
+ /// Dimensions of the IFFT that will result
+ pub fn n_fft(self) -> usize {
+ self.record() * self.resolution
+ }
+
+ /// Folded legth in taps
+ pub fn half_len(self) -> usize {
+ self.periods * self.resolution + 1
+ }
+
+ /// Reach of the returned taps in `u`, i.e. the largest `u` a resample can index.
+ pub fn reach(self) -> f64 {
+ (self.half_len() - 1) as f64 / self.resolution as f64
+ }
+
+ /// Post-elbow reference settings. Additional precision will buy only noise or regression.
+ pub fn reference() -> Self {
+ Self {
+ periods: 8,
+ pad: 42,
+ resolution: 1024,
+ }
+ }
+}
+
+impl Default for IfftSettings {
+ /// Standard settings are near the elbows of precision and will produce agreement with other
+ /// methods from about 1e-14 near the origin to 1e-8 near where padding begins.
+ fn default() -> Self {
+ Self {
+ periods: 8,
+ pad: 32,
+ resolution: 512,
+ }
+ }
+}
+
+/// Use an IFFT to generate time-domain solutions for psi, d, and dd.
+///
+/// The result covers `settings.periods` carrier cycles at `settings.resolution` samples per cycle,
+/// so `psi.len() == settings.half_len()`.
+///
+/// `settings.n_fft()` is the transform size.
+///
+/// Each array is the next in the storage convention, `dψ/du = 2πi·d` and `dd/du = 2πi·dd`, so
+/// `psi` and `d` both carry exact slopes for Hermite reconstruction.
+pub(crate) fn morse_half_taps(
+ shape: Shape,
+ settings: IfftSettings,
+) -> (Vec, Vec, Vec) {
+ let record = settings.record() as f64;
+ let half_len = settings.half_len();
+ let resolution = settings.resolution as f64;
+
+ let zeta_per_bin = 1.0 / record;
+ let beta_per_gamma = shape.beta / shape.gamma;
+
+ // Integer binade shift placing the spectral peak in [1, 2). Exponent-only, so folding it
+ // back out through `norm` restores the mantissa exactly.
+ // let peak = shape.peak();
+ // let shift = -((shape.beta * peak.ln() - peak.powf(shape.gamma)) / LN_2).floor();
+
+ // Ψ(1) = 2
+ let norm = 2.0 / record;
+
+ // The envelope underflows well before the Nyquist bin, so the significant support is far
+ // shorter than the transform would be. Collect it once and reuse across all samples.
+ let bins: Vec<[f64; 4]> = (1..settings.n_fft() / 2)
+ .map(|j| {
+ let zeta = j as f64 * zeta_per_bin;
+ // y = γ ln ζ
+ let y = shape.gamma * ((j as f64 - record) / record).ln_1p();
+ // ln Ψ(ζ) = (β/γ)(y − (e^y − 1))
+ let mag = (beta_per_gamma * (y - y.exp_m1())).exp();
+ [j as f64, mag, mag * zeta, mag * zeta * zeta]
+ })
+ .filter(|b| b[1] > 0.0)
+ .collect();
+
+ let mut psi = Vec::with_capacity(half_len);
+ let mut d = Vec::with_capacity(half_len);
+ let mut dd = Vec::with_capacity(half_len);
+
+ for i in 0..half_len {
+ let u = i as f64 / resolution;
+ let mut acc = [0.0f64; 6];
+ let mut comp = [0.0f64; 6];
+
+ for &[j, w_psi, w_d, w_dd] in &bins {
+ let (sin, cos) = (TAU * frac_turns(j, u, record)).sin_cos();
+ for (j, (w, trig)) in [
+ (w_psi, cos),
+ (w_psi, sin),
+ (w_d, cos),
+ (w_d, sin),
+ (w_dd, cos),
+ (w_dd, sin),
+ ]
+ .into_iter()
+ .enumerate()
+ {
+ let x = w * trig;
+ let x_err = w.mul_add(trig, -x);
+ let t = acc[j] + x;
+ comp[j] += (acc[j] - (t - x)) + (x - (t - acc[j])) + x_err;
+ acc[j] = t;
+ }
+ }
+
+ let mut out =
+ |j: usize| Complex64::new((acc[j] + comp[j]) * norm, (acc[j + 1] + comp[j + 1]) * norm);
+ psi.push(out(0));
+ d.push(out(2));
+ dd.push(out(4));
+ }
+
+ (psi, d, dd)
+}
+
+/// Fractional turns of `j*u/record`, carrying the low half of the product.
+///
+/// The phase reaches tens of thousands of radians at high `u`; reducing in turns before
+/// scaling by TAU keeps the argument reduction out of `sin_cos`.
+#[inline]
+fn frac_turns(j: f64, u: f64, record: f64) -> f64 {
+ let p_hi = j * u;
+ let p_lo = j.mul_add(u, -p_hi);
+ let q_hi = p_hi / record;
+ let q_lo = ((-q_hi).mul_add(record, p_hi) + p_lo) / record;
+ (q_hi - q_hi.floor()) + q_lo
+}
+
+#[cfg(test)]
+mod test {
+ use super::super::{fmt_e, hermite, quadjet};
+ use super::*;
+
+ #[test]
+ fn convergence_precision() {
+ // Find the grid and padding elbows. Remaining disagreement in other tests is disagreement
+ // about the wavelet rather than disagreement with self. Tests show that padding has the
+ // largest effect on accuracy. Grid size has relatively little influence relative to padding.
+
+ let shape = Shape::from_q(3.5, 3.0);
+
+ let reference = IfftSettings::reference();
+
+ let (ref_psi, ref_d, _) = morse_half_taps(shape, reference);
+
+ let rel = |v: Complex64, r: Complex64| (v - r).norm() / r.norm();
+
+ // Deliberately off-grid at every resolution in the sweep.
+ let probes = [
+ 0.0, 0.123, 0.37, 0.89, 1.31, 2.07, 2.66, 3.42, 4.19, 5.88, 6.42, 7.911,
+ ];
+
+ let refs: Vec<_> = probes
+ .iter()
+ .map(|&u| {
+ hermite::resample_hermite(
+ &ref_psi,
+ &ref_d,
+ u * reference.resolution as f64,
+ reference.resolution,
+ )
+ })
+ .collect();
+
+ let sweep =
+ |name: &str, knob: &str, vary: &dyn Fn(u32) -> (usize, IfftSettings), rows: u32| {
+ println!("\n=== {name} ===");
+ print!(" {knob:>10} |");
+ for u in probes {
+ print!(" {u:>9.2}");
+ }
+ println!();
+
+ for i in 0..rows {
+ let (label, settings) = vary(i);
+ let (psi, d, _) = morse_half_taps(shape, settings);
+
+ print!(" {label:>10} |");
+ for (&u, &psi_ref) in probes.iter().zip(&refs) {
+ let t = u * settings.resolution as f64;
+ let e = rel(
+ hermite::resample_hermite(&psi, &d, t, settings.resolution),
+ psi_ref,
+ );
+ print!(" {:>9}", fmt_e(e));
+ }
+ println!();
+ }
+ };
+
+ sweep(
+ "Cranking pad",
+ "pad",
+ &|i| {
+ let pad = (i as usize + 1) * 2;
+ (pad, IfftSettings { pad, ..reference })
+ },
+ 32,
+ );
+ sweep(
+ "Cranking resolution",
+ "resolution",
+ &|i| {
+ let resolution = (i as usize + 1) * 4;
+ (
+ resolution,
+ IfftSettings {
+ resolution,
+ ..reference
+ },
+ )
+ },
+ 32,
+ );
+
+ println!("\n=== Shipping Grid ===");
+ let shipping = IfftSettings::default();
+ let (psi, d, _) = morse_half_taps(shape, shipping);
+
+ let mut worst: f64 = 0.0;
+ let mut worst_u: f64 = 0.0;
+
+ for j in 0..=150 {
+ let u = j as f64 * 0.05 + 0.011;
+ let e = rel(
+ hermite::resample_hermite(
+ &psi,
+ &d,
+ u * shipping.resolution as f64,
+ shipping.resolution,
+ ),
+ hermite::resample_hermite(
+ &ref_psi,
+ &ref_d,
+ u * reference.resolution as f64,
+ reference.resolution,
+ ),
+ );
+ if e > worst {
+ worst = e;
+ worst_u = u;
+ }
+
+ if j % 10 == 0 {
+ println!(" u: {u:>6.2}, err: {:>9}", fmt_e(e));
+ }
+ }
+
+ println!(" worst over grid: {} at {:0.2}", fmt_e(worst), worst_u);
+ assert!(worst < 1e-5);
+ }
+
+ #[test]
+ fn quadrature_precision() {
+ // Hermite quadrature of psi over half periods, against an over-provisioned instance of
+ // itself. This is the same stencil `resample_hermite` uses, so a column reports when the
+ // stored psi stops carrying the area downstream will reconstruct.
+ //
+ // Bounds are quarter-period fractions straddling the carrier's zero crossings, so each
+ // column is one signed lobe and successive columns alternate sign. A whole-period window
+ // would cancel and report on the cancellation instead of the grid.
+
+ let shape = Shape::from_q(3.5, 3.0);
+
+ let reference = IfftSettings::reference();
+
+ // Half periods 0..10, covering the first five carrier periods.
+ const LOBES: usize = 10;
+
+ let (ref_psi, ref_d, _) = morse_half_taps(shape, reference);
+
+ // One signed lobe, straddling the carrier's zero crossings.
+ let bounds = |j: usize| ((1 + 2 * j) as f64 * 0.25, (3 + 2 * j) as f64 * 0.25);
+ let rho = |s: IfftSettings| 1.0 / s.resolution as f64;
+
+ let refs: Vec = (0..LOBES)
+ .map(|j| {
+ let (u0, u1) = bounds(j);
+ hermite::integrate(&ref_psi, &ref_d, u0, u1, rho(reference))
+ })
+ .collect();
+
+ let sweep = |name: &str, knob: &str, vary: &dyn Fn(u32) -> IfftSettings, rows: u32| {
+ println!("\n=== {name} ===");
+ print!(" {knob:>10} |");
+ for j in 0..LOBES {
+ print!(" {:>9.2}", 0.25 + j as f64 * 0.5);
+ }
+ println!();
+
+ for i in 0..rows {
+ let settings = vary(i);
+ let label = if knob == "pad" {
+ settings.pad
+ } else {
+ settings.resolution
+ };
+ let (psi, d, _) = morse_half_taps(shape, settings);
+
+ print!(" {label:>10} |");
+ for (j, &area_ref) in refs.iter().enumerate() {
+ let (u0, u1) = bounds(j);
+ let area = hermite::integrate(&psi, &d, u0, u1, rho(settings));
+ print!(" {:>9}", fmt_e((area - area_ref).norm() / area_ref.norm()));
+ }
+ println!();
+ }
+ };
+
+ sweep(
+ "Cranking pad",
+ "pad",
+ &|i| IfftSettings {
+ pad: (i as usize + 1) * 1,
+ // resolution: 1 << 12,
+ ..reference
+ },
+ 20,
+ );
+ // Truncation floor has to sit below the interpolation error at every row, so pad tracks the
+ // resolution rather than sitting at a fixed over-provision.
+ sweep(
+ "Cranking resolution",
+ "resolution",
+ &|i| IfftSettings {
+ // pad: 32,
+ resolution: (i as usize + 1) * 8,
+ ..reference
+ },
+ 32,
+ );
+
+ // Acceptance: the shipping grid sits past both elbows, so the area it carries differs from
+ // the reference only by floor.
+ println!("\n=== Shipping Grid ===");
+ let shipping = IfftSettings::default();
+ let (psi, d, _) = morse_half_taps(shape, shipping);
+ let mut worst: f64 = 0.0;
+
+ for (j, &area_ref) in refs.iter().enumerate() {
+ let (u0, u1) = bounds(j);
+ let area = hermite::integrate(&psi, &d, u0, u1, rho(shipping));
+ let e = (area - area_ref).norm() / area_ref.norm();
+ worst = worst.max(e);
+
+ println!(
+ " u: {:>6.2}, area: {:+9.7}, err: {:>9}",
+ 0.25 + j as f64 * 0.5,
+ area,
+ fmt_e(e)
+ );
+ }
+
+ println!(" worst over lobes: {}", fmt_e(worst));
+ assert!(worst < 1e-6);
+ }
+
+ // MAYBE sigh... what to do with you. Use of the production method as an... "oracle" to verify
+ // the IFFT accuracy convergence basically gives us a smoke test that confirms or at least
+ // demonstrates the error floor. Testing on-grid vs off-grid points (with and without Hermite
+ // interpolation error) may be informative at some point. An exercise left for the reader.
+ #[test]
+ fn accuracy_convergence() {
+ // Reconstruct taps at arbitrary `u` by Hermite resampling against the QuadJet as an oracle.
+ // Errors are normalized to the oracle's amplitude at the nearest half-phase, so a column
+ // tracks the local extrema.
+
+ // Amplitude has to clear the roundoff floor by this much before a cell reports.
+ const LIVE: f64 = 16.0;
+ const TOL: f64 = 1e-4; // Around u = 7, IFFT and QuadJet start to disagree enough to trip.
+
+ let shape = Shape::from_q(3.5, 3.0);
+ let oracle = quadjet::QuadJet::reference(shape);
+
+ let reference = IfftSettings::reference();
+
+ let rel = |v: Complex64, r: Complex64, scale: f64| (v - r).norm() / scale;
+
+ // Snap to a half period so a probe is scored against the previous extremum it sits just
+ // after, not the local error of a zero crossing which would produce an unstable ruler.
+ let local_scale = |u: f64| {
+ let anchor = (u * 2.0).floor() / 2.0;
+ oracle.tap_at(anchor)
+ };
+
+ // Deliberately off-grid at every resolution in the sweep.
+ let probes = [
+ 0.37, 1.31, 2.66, 3.42, 4.19, 4.77, 5.31, 5.88, 6.42, 6.94, 7.54,
+ ];
+
+ let refs: Vec<_> = probes
+ .iter()
+ .map(|&u| (oracle.tap_at(u), local_scale(u)))
+ .collect();
+
+ let peak = refs[0].1.psi.norm();
+
+ print!("\n {:>10} |", "decay");
+ for (_, ps) in &refs {
+ print!(" {:>9}", fmt_e(ps.psi.norm() / peak));
+ }
+ println!();
+
+ #[derive(Clone, Copy)]
+ enum Tap {
+ Psi,
+ D,
+ }
+
+ let sweep =
+ |tap: Tap, name: &str, knob: &str, vary: &dyn Fn(u32) -> IfftSettings, rows: u32| {
+ let label_tap = match tap {
+ Tap::Psi => "psi",
+ Tap::D => "d",
+ };
+ println!("\n=== {name} ({label_tap}) ===");
+ print!(" {knob:>10} |");
+ for u in probes {
+ print!(" {u:>9.2}");
+ }
+ println!();
+
+ for i in 0..rows {
+ let settings = vary(i);
+ let label = match knob {
+ "periods" => settings.periods,
+ "pad" => settings.pad,
+ "record" => settings.record(),
+ _ => settings.resolution,
+ };
+ let (psi, d, dd) = morse_half_taps(shape, settings);
+ let (value, slope) = match tap {
+ Tap::Psi => (&psi, &d),
+ Tap::D => (&d, &dd),
+ };
+ let reach = settings.reach();
+ let floor = (settings.n_fft() as f64).log2().sqrt() * f64::EPSILON * peak;
+
+ print!(" {label:>10} |");
+ for (&u, &(ref psi_ref, ref anchor)) in probes.iter().zip(&refs) {
+ let (reference, scale) = match tap {
+ Tap::Psi => (psi_ref.psi, anchor.psi.norm()),
+ Tap::D => (psi_ref.d, anchor.d.norm()),
+ };
+
+ // Skip cells that won't have an index due to being too short.
+ if u >= reach - 1.0 / settings.resolution as f64 {
+ print!(" {:>9}", "-");
+ continue;
+ }
+
+ let t = u * settings.resolution as f64;
+ let cell = format!(
+ "{:>9}",
+ fmt_e(rel(
+ hermite::resample_hermite(value, slope, t, settings.resolution),
+ reference,
+ scale
+ ))
+ );
+
+ // LIES When the predicted IFFT noise floor is higher than the scale of the
+ // features we are attempting to draw. The prediction may be loose or we may
+ // just be truly above the noise floor in average cases. Leaving this here in
+ // case this failure mode is encountered.
+ if scale < floor * LIVE {
+ print!(" \x1b[2;90m{cell}\x1b[0m");
+ } else {
+ print!(" {cell}");
+ }
+ }
+
+ println!();
+ }
+ };
+
+ // Each sweep is over-provisioned in the knobs it isn't varying, so the only thing that can
+ // bind is the one in the label.
+ for tap in [Tap::Psi, Tap::D] {
+ // Drive up the FFT grid points per period, resulting in finer sampling of the wavelet
+ // in the time domain.
+ sweep(
+ tap,
+ "Cranking resolution",
+ "resolution",
+ &|i| IfftSettings {
+ resolution: 8 + (i as usize * 16),
+ ..reference
+ },
+ 17,
+ );
+
+ // Add padding to constant period count.
+ sweep(
+ tap,
+ "Cranking pad",
+ "pad",
+ &|i| IfftSettings {
+ pad: i as usize * 2 + 2,
+ ..reference
+ },
+ 16,
+ );
+ }
+
+ println!("\n=== Shipping Grid ===");
+
+ let shipping = IfftSettings::default();
+ let (psi, d, _) = morse_half_taps(shape, shipping);
+
+ let noise = (shipping.n_fft() as f64).log2().sqrt() * f64::EPSILON * peak;
+ let floor = noise.max(oracle.tol * peak);
+
+ let reach = shipping.reach();
+
+ let mut worst = (0.0f64, 0.0f64);
+ let mut drift = (0.0f64, 0.0f64);
+ let mut live_to = 0.0f64;
+
+ println!(
+ " {:>6} | {:>9} | {:>9} | {:>9}",
+ "u", "psi", "ifft-psi", "decay"
+ );
+
+ let steps = ((reach - 0.011) / 0.05) as u32;
+
+ for j in 0..steps {
+ let u = j as f64 * 0.05 + 0.011;
+ let t = u * shipping.resolution as f64;
+ let scale = local_scale(u).psi.norm();
+
+ let e = rel(
+ hermite::resample_hermite(&psi, &d, t, shipping.resolution),
+ oracle.tap_at(u).psi,
+ scale,
+ );
+
+ // Nearest grid index; the oracle is exact at any `u`, so evaluating it *there*
+ // isolates solver-vs-solver drift from Hermite error.
+ let idx = t.round() as usize;
+ let u_grid = idx as f64 / shipping.resolution as f64;
+ let g = rel(psi[idx], oracle.tap_at(u_grid).psi, scale);
+
+ if j % 10 == 0 {
+ println!(
+ " {u:>6.2} | {:>9} | {:>9} | {:>9}",
+ fmt_e(e),
+ fmt_e(g),
+ fmt_e(scale / peak)
+ );
+ }
+
+ if scale <= floor * LIVE {
+ continue;
+ }
+
+ live_to = u;
+ if g > drift.0 {
+ drift = (g, u);
+ }
+ if e > worst.0 {
+ worst = (e, u);
+ }
+ }
+
+ println!(
+ "\n floor {} at peak scale (ifft {}, oracle {})",
+ fmt_e(floor / peak),
+ fmt_e(noise / peak),
+ fmt_e(oracle.tol)
+ );
+ println!(
+ " psi: worst {} at u {:.3}, oracle drift {} at u {:.3}, live to u {:.2}",
+ fmt_e(worst.0),
+ worst.1,
+ fmt_e(drift.0),
+ drift.1,
+ live_to
+ );
+
+ assert!(worst.0 < TOL);
+ assert!(live_to > 5.5);
+ }
+}
diff --git a/mutate-lib/src/dsp/wavelet/generate/mod.rs b/mutate-lib/src/dsp/wavelet/generate/mod.rs
new file mode 100644
index 00000000..714be2fc
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/generate/mod.rs
@@ -0,0 +1,569 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # Generate Wavelets
+//!
+//! > I am incensed that the features I require have been so thoroughly neglected only so that
+//! > this utter slop could be rushed into the hands of mere others who inconsiderately do not share
+//! > my specific requirements, and I will hold accountable the selfish cretins responsible for what
+//! > yesterday I did not know that I must have.
+//! >
+//! > - Ttang Kong
+//!
+//! High resolution mother wavelets from which our highly tuned but fundamentally rough N-tap
+//! filters are made. What that the restriction attempts to preserve is first measured from these
+//! high-fidelity inputs, so we try to make them good.
+//!
+//! Ideally both quick and accurate, but perhaps split between debug and release or offline baking
+//! where tradeoffs must be made. Downstream uses `f64` for several steps, but the restriction
+//! itself washes away *unbiased* noise during the reduction to `N` taps. The final shape-aware
+//! rounding to `f32` forgets any inaccuracy accumulated below its own precision. The final word is
+//! **avoid bias.**
+//!
+//! ## The Implementations
+//!
+//! Three implementations are contained. We use them to corroborate the wavelet engineering and
+//! verify the precision convergence of our approaches. The requirement is to establish convergence
+//! over the `f32` filter performance within the application. If numerical precision no longer
+//! limits our filter, we can focus on improving the filter we are approximating in N taps.
+//!
+//! - **IFFT** - the standard baseline. Precision is flat and relative error climbs at high `u`.
+//! - **Deformed Contour** - a reference implementation
+//! - **QuadJet** - the production implementation, precise, fast, and accurate, choose three.
+//!
+//! All generators evaluate the same one-sided inverse transform in the same
+//! units. `samples_per_period` (`S`) resolves the carrier into samples and *is* the 𝛚 in carrier
+//! radians per sample. The output taps are `ψ/S` and `-i d/S²`. The dilation step, where the
+//! daughter wavelet sample omega is known, applies both. Normalization and bank compensation are
+//! the caller's responsibility.
+
+#[cfg(all(test, feature = "validate"))]
+pub(crate) mod contour;
+#[cfg(all(test, feature = "validate"))]
+pub(crate) mod ifft;
+#[cfg(test)]
+use super::fmt_e;
+
+pub(crate) mod hermite;
+pub(crate) mod quadjet;
+
+use num_complex::Complex64;
+
+use crate::dsp::wavelet::whatsleft::Accumulator;
+use crate::dsp::wavelet::Shape;
+
+// NOTE The doc comments are getting really dense. While it's fun to play educator, I'd like to
+// focus on getting the nomenclature to presume the reader is familiar with a **good** model for
+// these problems and focus on getting across the choices in place for key conventions where most
+// people choose one or the other formalism.
+// NEXT Self-evaluation precision convergence tests are exactly just that. DFT tests are the
+// ultimate discriminator and only DFT can verify accurate wavelet generation. One may yet bet an
+// imposter. 🥷🏿
+// NOTE We're interested in bias, not extra precision. We can barely measure bias any more
+// accurately with extra precision, but a large bias, we have plenty of precision to measure. Bias
+// will show up even after we squeeze the result through a stencil. Noise will just get washed away
+// in the stencil and f32 truncation.
+// NEXT Did not compare any other FFT libraries, just went with stock standard.
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ use core::f64::consts::TAU;
+
+ const TRUST_DIGITS: f64 = 5.5;
+
+ // If bad > worst, worst = bad, location = u.
+ struct Extreme {
+ value: f64,
+ u: f64,
+ keep_min: bool,
+ }
+
+ impl Extreme {
+ fn min() -> Self {
+ Self {
+ value: f64::INFINITY,
+ u: 0.0,
+ keep_min: true,
+ }
+ }
+ fn max() -> Self {
+ Self {
+ value: f64::NEG_INFINITY,
+ u: 0.0,
+ keep_min: false,
+ }
+ }
+ fn see(&mut self, value: f64, u: f64) {
+ let better = if self.keep_min {
+ value < self.value
+ } else {
+ value > self.value
+ };
+ if better {
+ self.value = value;
+ self.u = u;
+ }
+ }
+ }
+
+ fn digits(x: f64) -> f64 {
+ if x <= 1e-17 {
+ 17.0
+ } else {
+ -x.log10()
+ }
+ }
+
+ fn digits_complex(a: Complex64, b: Complex64, scale: f64) -> f64 {
+ digits((a - b).norm() / scale)
+ }
+
+ #[cfg(feature = "validate")]
+ #[test]
+ fn multi_cross_reference_psi() {
+ // We compare the standard jet to its quadrature-only reference behavior. The reference is
+ // then compared to contour and ifft. Whichever of the three non-jet methods agrees better
+ // is taken as the goal. Standard jet sags versus the goal will be tracked as a precision
+ // deficit and asserted on. Worst pairs are reported, but it's known that IFFT at high u
+ // sags and mid-u Contour sags vs IFFT and reference QuadJet.
+
+ use std::time::{Duration, Instant};
+
+ let shape = Shape::from_q(3.5, 3.0);
+ let beta = shape.beta;
+
+ let settings = ifft::IfftSettings {
+ periods: 10,
+ ..ifft::IfftSettings::default()
+ };
+
+ let ifft_nominal_taps = settings.periods * settings.resolution;
+ let ifft_start = Instant::now();
+ let (psi, _, _) = ifft::morse_half_taps(shape, settings);
+ let ifft_us_per_tap = ifft_start.elapsed().as_secs_f64() * 1e6 / ifft_nominal_taps as f64;
+
+ let ref_jet = quadjet::QuadJet::reference(shape);
+ let std_jet = quadjet::QuadJet::standard(shape);
+
+ let res = settings.resolution as f64;
+ let stride = settings.resolution / 4;
+ let last = (10.0 * res) as usize;
+
+ let mut worst_qs_qr = Extreme::min();
+ let mut worst_qr_c = Extreme::min();
+ let mut worst_qr_i = Extreme::min();
+ let mut worst_c_i = Extreme::min();
+ let mut worst_qs_deficit = Extreme::max();
+
+ let mut contour_time = Duration::ZERO;
+ let mut ref_time = Duration::ZERO;
+ let mut std_time = Duration::ZERO;
+ let mut taps: u64 = 0;
+
+ println!("\n=== pairwise agreement, beta {beta:3.2} ===");
+ println!(
+ " {:>6} | {:>9} | {:>5} {:>5} {:>5} {:>5} | {:>5}",
+ "u", "scale", "qs-qr", "qr-c", "qr-i", "c-i", "defct"
+ );
+
+ for k in (0..=last).step_by(stride) {
+ let u = k as f64 / res;
+
+ let ifft = psi[k];
+
+ let t = Instant::now();
+ let contour = contour::tap_at(shape, u);
+ contour_time += t.elapsed();
+
+ let t = Instant::now();
+ let reference = ref_jet.tap_at(u);
+ ref_time += t.elapsed();
+
+ let t = Instant::now();
+ let standard = std_jet.tap_at(u);
+ std_time += t.elapsed();
+
+ taps += 1;
+
+ let scale = ifft.norm().max(contour.value.norm());
+
+ let qs_qr = digits_complex(standard.psi, reference.psi, scale);
+ let qr_c = digits_complex(reference.psi, contour.value, scale);
+ let qr_i = digits_complex(reference.psi, ifft, scale);
+ let c_i = digits_complex(contour.value, ifft, scale);
+
+ worst_qs_qr.see(qs_qr, u);
+ worst_qr_c.see(qr_c, u);
+ worst_qr_i.see(qr_i, u);
+ worst_c_i.see(c_i, u);
+
+ // The best-agreeing pair among the three non-jet comparisons sets the bar. Below
+ // TRUST_DIGITS none of the three is corroborated enough to trip, so the assertion on
+ // jet's agreement with quadrature-only is leaned on in a separate assert.
+ let goal = qr_c.max(qr_i).max(c_i);
+ let deficit = if goal > TRUST_DIGITS {
+ (goal - qs_qr).max(0.0)
+ } else {
+ 0.0
+ };
+ worst_qs_deficit.see(deficit, u);
+
+ println!(
+ " {u:>6.3} | {:>9} | {qs_qr:>5.1} {qr_c:>5.1} {qr_i:>5.1} {c_i:>5.1} | {deficit:>5.1}",
+ fmt_e(scale),
+ );
+ }
+
+ println!(
+ " worst qs-qr: {:.1} digits at u {:.3}",
+ worst_qs_qr.value, worst_qs_qr.u
+ );
+ println!(
+ " worst qr-c: {:.1} digits at u {:.3}",
+ worst_qr_c.value, worst_qr_c.u
+ );
+ println!(
+ " worst qr-i: {:.1} digits at u {:.3}",
+ worst_qr_i.value, worst_qr_i.u
+ );
+ println!(
+ " worst c-i: {:.1} digits at u {:.3}",
+ worst_c_i.value, worst_c_i.u
+ );
+ println!(
+ " worst qs deficit: {:.1} digits at u {:.3}",
+ worst_qs_deficit.value, worst_qs_deficit.u
+ );
+
+ let contour_us_per_tap = contour_time.as_secs_f64() * 1e6 / taps as f64;
+ let ref_us_per_tap = ref_time.as_secs_f64() * 1e6 / taps as f64;
+ let std_us_per_tap = std_time.as_secs_f64() * 1e6 / taps as f64;
+
+ println!("\n=== per-tap cost ===");
+ println!(" {:>22} | {:>8}", "method", "us/tap");
+ println!(
+ " {:>22} | {:>8.3}",
+ format!("ifft ({ifft_nominal_taps})"),
+ ifft_us_per_tap
+ );
+ println!(" {:>22} | {:>8.3}", "contour", contour_us_per_tap);
+ println!(" {:>22} | {:>8.3}", "quadjet (reference)", ref_us_per_tap);
+ println!(" {:>22} | {:>8.3}", "quadjet (standard)", std_us_per_tap);
+
+ assert!(worst_qr_c.value.max(worst_qr_i.value).max(worst_c_i.value) > 3.0);
+ assert!(worst_qs_qr.value > 6.0);
+ // Pull this up as the remaining dips go away.
+ assert!(worst_qs_deficit.value < 9.0);
+ }
+
+ #[cfg(feature = "validate")]
+ #[test]
+ fn multi_cross_reference_d() {
+ // `d` channel check. The quadrature-only jet is the reference and IFFT is its independent
+ // corroboration. Where the two agree, the standard jet is expected to follow, and its sag
+ // is the deficit.
+
+ // use a slightly different q to smoke test without sweep.
+ let shape = Shape::from_q(24.5, 3.0);
+ let beta = shape.beta;
+
+ let settings = ifft::IfftSettings {
+ periods: 10,
+ ..ifft::IfftSettings::default()
+ };
+
+ let (_, d, _) = ifft::morse_half_taps(shape, settings);
+
+ let ref_jet = quadjet::QuadJet::reference(shape);
+ let std_jet = quadjet::QuadJet::standard(shape);
+
+ let res = settings.resolution as f64;
+ let stride = settings.resolution / 4;
+ // NOTE IFFT precision in `d` is likely falling off even faster than `psi`, so we just cap
+ // the test over a reasonable range to smoke test the conventions. To investigate more
+ // thoroughly, implement `d` for the contour and add it to the test.
+ let last = (5.0 * res) as usize;
+
+ let mut worst_qs_qr = Extreme::min();
+ let mut worst_qr_i = Extreme::min();
+ let mut worst_qs_deficit = Extreme::max();
+
+ println!("\n=== pairwise agreement on d, beta {beta:3.2} ===");
+ println!(
+ " {:>6} | {:>9} | {:>5} {:>5} | {:>5}",
+ "u", "scale", "qs-qr", "qr-i", "defct"
+ );
+
+ for k in (0..=last).step_by(stride) {
+ let u = k as f64 / res;
+
+ let ifft = d[k];
+ let reference = ref_jet.tap_at(u);
+ let standard = std_jet.tap_at(u);
+
+ let scale = ifft.norm().max(reference.d.norm());
+
+ let qs_qr = digits_complex(standard.d, reference.d, scale);
+ let qr_i = digits_complex(reference.d, ifft, scale);
+
+ worst_qs_qr.see(qs_qr, u);
+ worst_qr_i.see(qr_i, u);
+
+ // IFFT corroborating the reference sets the bar, and below TRUST_DIGITS nothing is
+ // corroborated well enough to trip.
+ let deficit = if qr_i > TRUST_DIGITS {
+ (qr_i - qs_qr).max(0.0)
+ } else {
+ 0.0
+ };
+ worst_qs_deficit.see(deficit, u);
+
+ println!(
+ " {u:>6.3} | {:>9} | {qs_qr:>5.1} {qr_i:>5.1} | {deficit:>5.1}",
+ fmt_e(scale),
+ );
+ }
+
+ println!(
+ " worst qs-qr: {:.1} digits at u {:.3}",
+ worst_qs_qr.value, worst_qs_qr.u
+ );
+ println!(
+ " worst qr-i: {:.1} digits at u {:.3}",
+ worst_qr_i.value, worst_qr_i.u
+ );
+ println!(
+ " worst qs deficit: {:.1} digits at u {:.3}",
+ worst_qs_deficit.value, worst_qs_deficit.u
+ );
+
+ assert!(worst_qr_i.value > 6.0);
+ assert!(worst_qs_qr.value > 7.0);
+ // Pull this up as the remaining dips go away.
+ assert!(worst_qs_deficit.value < 10.0);
+ }
+
+ #[cfg(feature = "validate")]
+ #[test]
+ fn omega_check() {
+ const TAPS: usize = 256;
+ const DECIMATE: usize = 8;
+
+ let shape = Shape::from_q(23.6, 3.0);
+
+ let settings = ifft::IfftSettings {
+ periods: 10,
+ ..ifft::IfftSettings::default()
+ };
+ let (psi, _, _) = ifft::morse_half_taps(shape, settings);
+
+ let std_jet = quadjet::QuadJet::standard(shape);
+ let res = settings.resolution as f64 / DECIMATE as f64;
+
+ // Both methods are read on the ifft grid so the two omegas share an abscissa.
+ let taps: Vec<(Complex64, Complex64)> = (0..TAPS)
+ .map(|t| (psi[t * DECIMATE], std_jet.tap_at(t as f64 / res).psi))
+ .collect();
+
+ println!("\n=== omega, ifft versus standard jet ===");
+ println!(
+ " {:>3} {:>7} | {:>13} {:>10} | {:>13} {:>10} | {:>10}",
+ "t", "u", "omega i", "|psi| i", "omega qs", "|psi| qs", "d omega"
+ );
+
+ for t in 1..TAPS {
+ let (ifft, ifft_prev) = (taps[t].0, taps[t - 1].0);
+ let (std, std_prev) = (taps[t].1, taps[t - 1].1);
+
+ // Modulus cancels out of the argument, so it is reported only as a conditioning number.
+ let omega_i = (ifft * ifft_prev.conj()).arg();
+ let omega_s = (std * std_prev.conj()).arg();
+
+ println!(
+ " {t:>3} {:>7.4} | {omega_i:>+13.9} {:>10} | {omega_s:>+13.9} {:>10} | {:>+10.2e}",
+ t as f64 / res,
+ fmt_e(ifft.norm()),
+ fmt_e(std.norm()),
+ omega_s - omega_i,
+ );
+ }
+ }
+
+ #[cfg(feature = "validate")]
+ #[test]
+ fn hermite_precision_convergence() {
+ // Area under the Hermite stencil over two windows in half periods, one fully off-grid and
+ // one opening on a tap. Self columns are each method against its own finest grid, so they
+ // report the stencil alone. Cross columns are equal-grid method disagreement, which the
+ // area sees through both `psi` and `d`.
+
+ const FINEST: usize = 1 << 18;
+
+ let shape = Shape::from_q(3.5, 3.0);
+ let ref_jet = quadjet::QuadJet::reference(shape);
+ let std_jet = quadjet::QuadJet::standard(shape);
+
+ // Half period is 0.5 in `u`.
+ let windows = [
+ (0.5 / 3.0, 1.0 / 3.0),
+ (0.5, 2.0 / 3.0),
+ (1.5 + 1.0 / 7.0, 2.0 - 1.0 / 7.0),
+ (2.5 + 1.0 / 7.0, 3.0 - 1.0 / 7.0),
+ ];
+
+ let jet_area = |jet: &quadjet::QuadJet, grid_res: usize, u_beg: f64, u_end: f64| {
+ let count = (u_end * grid_res as f64).ceil() as usize + 2;
+ let taps: Vec<_> = (0..=count)
+ .map(|i| jet.tap_at(i as f64 / grid_res as f64))
+ .collect();
+ let psi: Vec = taps.iter().map(|t| t.psi).collect();
+ let d: Vec = taps.iter().map(|t| t.d).collect();
+ hermite::integrate(&psi, &d, u_beg, u_end, 1.0 / grid_res as f64)
+ };
+
+ let ifft_area = |grid_res: usize, u_beg: f64, u_end: f64| {
+ let settings = ifft::IfftSettings {
+ periods: 4,
+ pad: 42,
+ resolution: grid_res,
+ };
+ let (psi, d, _) = ifft::morse_half_taps(shape, settings);
+ hermite::integrate(&psi, &d, u_beg, u_end, 1.0 / grid_res as f64)
+ };
+
+ for (u_beg, u_end) in windows {
+ println!("\n=== hermite area on [{u_beg:.4}, {u_end:.4}] ===");
+ println!(
+ " {:>10} | {:>9} {:>9} {:>9} | {:>9} {:>9}",
+ "grid", "ifft", "qr", "qs", "qs-qr", "i-qr"
+ );
+
+ let ref_ifft = ifft_area(FINEST, u_beg, u_end);
+ let ref_qr = jet_area(&ref_jet, FINEST, u_beg, u_end);
+ let ref_qs = jet_area(&std_jet, FINEST, u_beg, u_end);
+ let scale = ref_qr.norm();
+
+ let rel = |v: Complex64, r: Complex64| (v - r).norm() / scale;
+
+ let mut worst_self = 0.0f64;
+ let mut worst_cross = 0.0f64;
+
+ for row in 3..=16u32 {
+ let grid_res = 1usize << row;
+
+ let i = ifft_area(grid_res, u_beg, u_end);
+ let qr = jet_area(&ref_jet, grid_res, u_beg, u_end);
+ let qs = jet_area(&std_jet, grid_res, u_beg, u_end);
+
+ let self_i = rel(i, ref_ifft);
+ let self_qr = rel(qr, ref_qr);
+ let self_qs = rel(qs, ref_qs);
+ let qs_qr = rel(qs, qr);
+ let i_qr = rel(i, qr);
+
+ println!(
+ " {grid_res:>10} | {:>9} {:>9} {:>9} | {:>9} {:>9}",
+ fmt_e(self_i),
+ fmt_e(self_qr),
+ fmt_e(self_qs),
+ fmt_e(qs_qr),
+ fmt_e(i_qr),
+ );
+
+ // The finest rows are the ones that have to have arrived.
+ if row >= 9 {
+ worst_self = worst_self.max(self_i.max(self_qr).max(self_qs));
+ worst_cross = worst_cross.max(qs_qr.max(i_qr));
+ }
+ }
+
+ println!(
+ " finest rows: worst self {}, worst cross {}",
+ fmt_e(worst_self),
+ fmt_e(worst_cross)
+ );
+
+ assert!(worst_self < 1e-9);
+ assert!(worst_cross < 1e-6);
+ }
+ }
+
+ /// Standard jet against IFFT on ψ, `d`, and Hermite area, swept over γ.
+ #[cfg(feature = "validate")]
+ #[test]
+ fn jet_tracks_ifft_across_gamma() {
+ const RES: usize = 512;
+
+ let windows = [
+ (0.5 / 3.0, 1.0 / 3.0),
+ (1.5 + 1.0 / 7.0, 2.0 - 1.0 / 7.0),
+ (2.5 + 1.0 / 7.0, 3.0 - 1.0 / 7.0),
+ ];
+
+ for (q, gamma) in [(4.5, 1.0), (8.5, 2.0), (4.5, 4.0), (8.5, 5.0)] {
+ let shape = Shape::from_q(q, gamma);
+ let settings = ifft::IfftSettings {
+ periods: 10,
+ pad: 42,
+ resolution: RES,
+ };
+ let (i_psi, i_d, _) = ifft::morse_half_taps(shape, settings);
+ let jet = quadjet::QuadJet::standard(shape);
+
+ let res = RES as f64;
+ let last = 5 * RES;
+ let taps: Vec<_> = (0..=last + 2).map(|k| jet.tap_at(k as f64 / res)).collect();
+ let j_psi: Vec = taps.iter().map(|t| t.psi).collect();
+ let j_d: Vec = taps.iter().map(|t| t.d).collect();
+
+ println!(
+ "\n=== jet vs ifft, q {q:.1} gamma {gamma:.1} beta {:.2} ===",
+ shape.beta
+ );
+ println!(
+ " {:>6} | {:>9} | {:>5} {:>5} | {:>9}",
+ "u", "scale", "psi", "d", "d ratio"
+ );
+
+ let mut worst_psi = Extreme::min();
+ let mut worst_d = Extreme::min();
+
+ for k in (0..=last).step_by(RES / 4) {
+ let u = k as f64 / res;
+ let scale_psi = i_psi[k].norm().max(j_psi[k].norm());
+ let scale_d = i_d[k].norm().max(j_d[k].norm());
+
+ let psi = digits_complex(j_psi[k], i_psi[k], scale_psi);
+ let d = digits_complex(j_d[k], i_d[k], scale_d);
+ worst_psi.see(psi, u);
+ worst_d.see(d, u);
+
+ println!(
+ " {u:>6.3} | {:>9} | {psi:>5.1} {d:>5.1} | {:>9.6}",
+ fmt_e(scale_d),
+ (j_d[k] / i_d[k]).re,
+ );
+ }
+
+ for (u_beg, u_end) in windows {
+ let rho = 1.0 / res;
+ let i = hermite::integrate(&i_psi, &i_d, u_beg, u_end, rho);
+ let j = hermite::integrate(&j_psi, &j_d, u_beg, u_end, rho);
+ println!(
+ " area [{u_beg:.4}, {u_end:.4}] rel {}",
+ fmt_e((j - i).norm() / i.norm())
+ );
+ }
+
+ println!(
+ " worst psi {:.1} digits at u {:.3}, worst d {:.1} digits at u {:.3}",
+ worst_psi.value, worst_psi.u, worst_d.value, worst_d.u
+ );
+
+ assert!(worst_psi.value > 7.0);
+ assert!(worst_d.value > 7.0);
+ }
+ }
+}
diff --git a/mutate-lib/src/dsp/wavelet/generate/quadjet.rs b/mutate-lib/src/dsp/wavelet/generate/quadjet.rs
new file mode 100644
index 00000000..d99c3c6a
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/generate/quadjet.rs
@@ -0,0 +1,2197 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # Log-Tilted Saddle Jet + Terminal Quadrature
+//!
+//! > Engineers don't know anything but physicists can't do anything.
+//! >
+//! > - Nigel Clayton
+//!
+//! This is the production method. It uses the log tilt to avoid endpoint terms at all. Heavy
+//! reliance on saddle terms is sufficient for many `u` and avoids expensive quadrature. Quadrature
+//! is used wherever the saddle terms struggle to do the job or to do it accurately. That's a lot
+//! of sophistication. The simpler IFFT and Contour methods are provided as evidence of this
+//! implementation's accuracy and precision.
+//!
+//! `∫₀^∞ ω^β e^{-ω^γ} e^{iωt} dω` by steepest descent in `z = ln(ω/ω_p)`. Working in the log
+//! coordinate carries the branch point at the origin out to infinity, so the saddle condition
+//! becomes the trinomial `q^γ - iτq - 1 = 0` in the normalized frequency `q = ω/ω_p`, and every
+//! derivative of the phase comes out affine in the single number `B = q^γ - 1`.
+//!
+//! The original contour decomposes into some subset of those saddles, and which subset is a matter
+//! of membership. At `τ = 0` the roots are the roots of unity and only one of them belongs.
+//! Membership changes as `τ` grows only where two saddles exchange dominance, so it has to be
+//! marched from that seed rather than evaluated at a point, and the march happens once. A tap is
+//! then a pure function of `t` and the caller owes us no grid continuity.
+//!
+//! Every saddle that survives is approached two ways. A Watson jet expands around it and costs
+//! almost nothing, and a trapezoid traced along its steepest-descent path costs a great deal
+//! more. The jet runs everywhere and reports what it could not resolve, and the path is spent
+//! only where that report says the series cannot reach the accuracy the caller asked for.
+//!
+//! `γ ≥ 3` is the supported range. At `γ = 2` two saddles collide on the real `τ` axis at
+//! `τ = 2` and `Φ''` vanishes with them, taking the normal coordinate the whole method is built
+//! on with it.
+//!
+//! ## Symbols
+//!
+//! This module uses specific coordinates for several steps and adopts conventions convenient to
+//! the integrand and its setup work, including log frequency saddle coordinates.
+//!
+//! ### Frequency and coordinates
+//!
+//! | symbol | Rust | object |
+//! |---|---|---|
+//! | `ω_p` | `peak` | `(β/γ)^{1/γ}`, the envelope's peak and the frequency scale `ω` is measured in |
+//! | `ω` | | the integration variable, frequency |
+//! | `q` | `q` | `ω/ω_p`, the normalized frequency |
+//! | `z` | | `ln(ω/ω_p) = ln q`, the log-frequency coordinate the descent runs in |
+//! | `v` | `v` | `z - z_j`, the local coordinate measured from saddle `j` |
+//! | `x` | `x` | the normal coordinate, where the phase is exactly `-x²/2` |
+//!
+//! ### Phase
+//!
+//! | symbol | Rust | object |
+//! |---|---|---|
+//! | `B` | `b` | `q^γ - 1`, the single number every derivative of the phase is affine in |
+//! | `g` | `g` | the phase in `v`, whose roots satisfy `g(v) = -x²/2` |
+//! | `Φ` | `phi` | the phase, zero at the `τ = 0` seed; at a root, `Φ = ln q + B(1 - 1/γ)` |
+//!
+//! ### Saddle geometry
+//!
+//! | symbol | Rust | object |
+//! |---|---|---|
+//! | `s₀` | `s0` | the resolved curvature at a saddle |
+//!
+//! ### Asymptotic / Stokes structure
+//!
+//! | symbol | Rust | object |
+//! |---|---|---|
+//! | `r*` | `r_star` | the nearest singulant modulus, where the jet's series turns |
+//! | `Δ` | `delta` | `β(Φ_j - Φ_i)`, the singulant a neighbor enters at |
+//! | `τ` | `tau` | `2πu/β`, the axis the Stokes march runs on |
+//!
+//! The coordinate chain is:
+//!
+//! `ω → q = ω/ω_p → z = ln q → v = z - z_j → x`
+//!
+//! with `x` chosen so that the local phase is exactly `-x²/2`.
+//!
+//! The Morse shape parameters, `beta` and `gamma` have their usual meaning. The `u` periods from
+//! the center tap is unchanged in usage elsewhere in the parent module.
+
+// NEXT the biggest *easy* improvement (besides making comments useful) is to go back to the
+// quadrature ladder, sharing nodes while refining, perhaps refining more where curvature is
+// detected.
+// NEXT biggest *possible* improvement is increase the number of saddles that can be handled and
+// possibly the Airy treatment, combining two saddles. The cost of the quadrature around steep
+// curvature changes near approaches by two roots basically dwarfs the rest of the runtime cost.
+// Investing in a little compute speed up on top of that would drop most solves to low digit micros.
+// NEXT Most of the constants have not had a proper sweep. Digging into the precision-cost
+// accounting will almost surely reveal that most of them need tweaks and many can be collapsed or
+// removed. They piled up in order of development. You have working module. You're welcome.
+
+// 🤖 This module exemplifies a principled approach to wrapping engineering around heuristically
+// generated code. The approach is similar to supplier quality assurance. Our shop might not build
+// widgets, but we can test that a widget behaves as expected, generating a wavelet to a degree of
+// accuracy that cannot be expected of a degenerate, malformed widget.
+//
+// First to verify that the approach had any hope at all, a reference implementation of the
+// quadrature, the deformed contour, was created. It has long agreed with a well understood
+// approach, the IFFT. Where the IFFT approach has self-converging precision (and the lucky
+// butterflies removed from this consideration), the deformed contour approach appears equally
+// precise.
+//
+// The deformed contour was selected via an analytic design canvas, a survey of well-formalized
+// approaches. Such a survey does not intend to understand each option up to the point of
+// fine-tuning a concrete implementation. Instead, it only aims to understand their qualities and
+// to identify *evidence* that the approach has some advantage over others. The output is an
+// ensemble of design choices that are believed likely to work well together. This is one phase of
+// risk management among many.
+//
+// The same process identified important design considerations, such as the rotated log coordinates,
+// as having desirable properties. Several simpler but similar implementations were built up and
+// checked against the IFFT and contour methods. The testing methodology was built up. The proper
+// signals were identified and built up.
+//
+// The degree of method-independent corroboration can be made so overwhelming that any other
+// evidence leaning solely on a prior is made vanishingly small. That doesn't constitute a formal
+// proof. Code usually does not (outside of safety critical applications with explicit formal
+// verification within the toolchain). What the corroboration becomes is a sufficient degree of
+// demonstrated reliability to be competitive with any other option.
+//
+// The IFFT approach, the COTS standard, the low-risk entry into the race, is not actually a low
+// risk approach without the same corroborating evaluation process. It was the lack of agreement
+// with the other methods that identified the IFFT's need for padding and how much. A low risk tool
+// used too eagerly without engineering acceptance testing is not a low risk tool. Advocating use
+// of such libraries and endlessly encouraging authors to make them infallible with the goal of
+// turning one's own brain off while using them is a familiar kind of laziness we should discourage.
+//
+// What remains worthy of emphasis is the importance of encouraging open discussion such of methods.
+// Code such as this is welcome in this project. It should be welcome in more projects, and it
+// should not be discussed dishonestly and lazily from the shaky foundations of repeatedly refuted,
+// outdated, and increasingly belying priors.
+//
+// Formally defined methods and the tools created from them do not often kind-of succeed.
+// Heuristics approximating implementation of formal methods are strongly attracted to grooves of
+// consistency. The coherence goes up. The attracting manifold attracts. Upon intersection with a
+// correct approach, at the intersection of a correct implementation, the result ceases to be a
+// heuristic output and has crossed into being an algorithm, a formally consistent approach that
+// always obtains a correct result. If a descent can be coaxed along a line that will fall into a
+// groove, a heuristic an be made to behave in a deterministic manner, and to pretend otherwise is
+// perhaps an instance of motivated failure to comprehend.
+use libm::erfc;
+use num_complex::Complex64;
+use std::f64::consts::{SQRT_2, TAU};
+
+use super::super::spec::Shape;
+use super::super::whatsleft::Accumulator;
+
+const EPS: f64 = f64::EPSILON;
+
+// Stokes table
+const DK_ITERS: usize = 32;
+const DK_TOL: f64 = 1e-16;
+const TABLE_NEWTON_TOL: f64 = 1e-16;
+const TABLE_NEWTON_ITERS: usize = 32;
+const TABLE_NODES: usize = 1024;
+const TABLE_QUIET_SPAN: f64 = 4.0;
+const TABLE_TAU_MAX: f64 = 128.0;
+
+// Saddle orientation
+const DESCENT_AXIS_TIE: f64 = 1e-12;
+
+// Sheet probing
+const SHEET_COS: f64 = 0.5;
+const PROBE_CLIP: f64 = 1.0 / 64.0;
+const PROBE_REACH: f64 = 8.0;
+const PROBE_SPREAD: f64 = 2.5;
+const PROBE_TRIES: u32 = 8;
+
+// Jets
+const ADJ_CONE: f64 = 0.5;
+const JET_ORDER: usize = 32;
+const JET_SLOTS: usize = JET_ORDER + 2;
+const JET_SETTLE_FLOOR: usize = 2;
+const JET_OVERSHOOT: f64 = 1.2;
+const LIVE: f64 = 1e-6;
+const STOKES_REACH: f64 = 4.0;
+const MAX_G: usize = 8;
+const TURN_CONFIRM: u32 = 2;
+
+// Quadrature
+const CALIBRATE_NODES: f64 = 2.0;
+const ANCHOR_EFOLDS: f64 = 3.0;
+const CERTIFY_DERATE: f64 = 0.35;
+const GAP_FLOOR: f64 = 1e-6;
+const LIFT_CREDIT: f64 = 1.0;
+const PLACE_MARGIN_EFOLDS: f64 = 2.0;
+const PLACE_STEP: f64 = 1.2;
+const NEWTON_TOL_FACTOR: f64 = 0.3;
+const NEWTON_SLACK: usize = 2;
+const PLACE_ROUNDS: u32 = 6;
+const QUAD_MAX_NODES: usize = 1024 * 16;
+const QUAD_MIN_DENSITY: f64 = 1e-3;
+const RATE_CREDIBLE: f64 = 4.0;
+const REACH_MARGIN: f64 = 3.0;
+const REACH_MAX: f64 = 16.0;
+const PREDICT_TRUST: f64 = 0.9;
+const PREDICT_DRIFT: f64 = 2.0;
+const SERIES_TRUST: f64 = 0.5;
+const TRACE_MAX_SPLIT: u32 = 8;
+
+/// The shape, together with the forms of it the rest of the file actually reads. `ω_p` is where
+/// the saddle sits at `τ = 0` and sets the scale `ω` is measured in, and the two integer casts
+/// of `γ` are what the loop bounds and `powi` want.e
+#[derive(Clone, Copy)]
+struct Frame {
+ beta: f64,
+ gamma: f64,
+ g: usize,
+ gi: i32,
+}
+
+impl Frame {
+ fn new(shape: Shape) -> Self {
+ let Shape { beta, gamma } = shape;
+ Self {
+ beta,
+ gamma,
+ g: gamma as usize,
+ gi: gamma as i32,
+ }
+ }
+}
+
+pub struct QuadJetResult {
+ pub psi: Complex64,
+ /// `−(i/2π)·dψ/du`, from the same roots and the same paths. See the parent module for the
+ /// storage convention.
+ pub d: Complex64,
+ /// What each saddle's own method could say about its own error, summed over the
+ /// decomposition, in the units of the channel it describes.
+ #[allow(unused)]
+ pub residual: f64,
+ /// Approximate spend for this tap.
+ #[allow(unused)]
+ pub cost: Cost,
+}
+
+/// Crude spend, for development signal only. Every column sums over the call tree of one tap,
+/// so the numbers are read against themselves across a change rather than against each other.
+#[derive(Clone, Copy, Default)]
+pub struct Cost {
+ /// `jet_pass` invocations.
+ pub jet_passes: u32,
+ /// Summed order reached.
+ pub jet_orders: u32,
+ /// The deepest order any single pass reached.
+ pub jet_depth: u32,
+ /// Saddles the jet was run on at all.
+ pub jet_saddles: u32,
+ /// `trapezoid` invocations.
+ pub quad_paths: u32,
+ /// Nodes a `walk` was actually spent on, summed over every level traced.
+ pub quad_nodes: u32,
+ /// Nodes the map's own series placed instead, which cost a Horner pass apiece.
+ pub quad_series: u32,
+ /// How far the traced path moved the jet's answer, measured against the bar that asked for
+ /// it. Under one, the series had already arrived wherever a path was spent.
+ pub quad_gain: f64,
+ /// A trace ran out of valley before the reach was spent, so part of the contour is carried
+ /// by the endpoint charge rather than by nodes.
+ pub quad_truncated: bool,
+ /// The placement stopped with the residual still above the bar it was given.
+ pub quad_short: bool,
+ pub quad_density_ratio: f64,
+ pub quad_rate_ratio: f64,
+}
+
+impl std::ops::AddAssign for Cost {
+ fn add_assign(&mut self, rhs: Self) {
+ self.jet_passes += rhs.jet_passes;
+ self.jet_orders += rhs.jet_orders;
+ self.jet_depth = self.jet_depth.max(rhs.jet_depth);
+ self.jet_saddles += rhs.jet_saddles;
+ self.quad_paths += rhs.quad_paths;
+ self.quad_nodes += rhs.quad_nodes;
+ self.quad_series += rhs.quad_series;
+ self.quad_gain = self.quad_gain.max(rhs.quad_gain);
+ self.quad_truncated |= rhs.quad_truncated;
+ self.quad_short |= rhs.quad_short;
+ self.quad_density_ratio = self.quad_density_ratio.max(rhs.quad_density_ratio);
+ self.quad_rate_ratio = self.quad_rate_ratio.max(rhs.quad_rate_ratio);
+ }
+}
+
+/// Both channels, together with whatever the producing method could say about its own error in
+/// `ψ`. Convergence is a question about `ψ` alone, so `dψ/du` carries a value and no verdict.
+struct Terms {
+ value: [Complex64; 2],
+ residual: f64,
+}
+
+/// A jet at one order, with whether the series ended on the mathematics or on the max order.
+struct Pass {
+ terms: Terms,
+ reached: usize,
+ spent: bool,
+ /// Met the bar it needed to cross.
+ settled: bool,
+ cost: Cost,
+}
+
+/// What a jet had to say, together with the last order that improved the sum. Everything above
+/// that order is the divergent tail and belongs to nobody.
+struct Expansion {
+ terms: Terms,
+ reached: usize,
+ cost: Cost,
+ /// Nothing left to expand
+ exhausted: bool,
+}
+
+/// Both channels plus the spend that produced them.
+struct Priced {
+ terms: Terms,
+ cost: Cost,
+}
+
+/// One traced level. The sum it came to, how far along the path it actually got, and whether
+/// that was the whole reach it was asked for. A walk that ran out of valley early owes an
+/// endpoint charge at the span it reached rather than the reach it was handed.
+struct Level {
+ resid: [Complex64; 2],
+ spans: [f64; 2],
+ /// The subtracted polynomial integrated back over the span this level covered.
+ moments: [Complex64; 2],
+ full: bool,
+ cost: Cost,
+}
+
+/// # QuadJet
+///
+/// Everything that depends on `γ` alone. The Stokes march is the expensive part and the same
+/// for every tap, so a tap reads this and writes only its own stack.
+pub struct QuadJet {
+ /// The accuracy being asked for, which sets both the bar a saddle's contribution is
+ /// measured against and the point at which the jet's residual buys a traced path.
+ pub tol: f64,
+ /// Morse wavelet parameters.
+ #[allow(unused)]
+ pub shape: Shape,
+ /// Skip the jet's verdict and trace every saddle, which is the mode the IFFT and contour
+ /// methods are compared against.
+ pub quadrature_only: bool,
+ /// What each saddle's own method could say about its error in `ψ`, summed over the
+ /// decomposition.
+ #[allow(unused)]
+ pub residual: f64,
+ frame: Frame,
+ table: StokesTable,
+
+ /// Scratch for the jet series, reused across taps. `seed` resets `width` at every saddle,
+ /// and every reader is bounded by `width`, so nothing here survives into an answer.
+ scratch: std::cell::UnsafeCell>,
+ /// The scratch is one buffer, so a `QuadJet` is not shareable across threads.
+ _unsync: std::marker::PhantomData<*const ()>,
+}
+
+impl QuadJet {
+ /// Caller is responsible that `beta > 0`, `gamma` an integer in `3..=MAX_G`.
+ pub fn new(shape: Shape, tol: f64, quadrature_only: bool) -> Self {
+ let frame = Frame::new(shape);
+ let table = StokesTable::build(&frame);
+ Self {
+ tol,
+ shape,
+ quadrature_only,
+ frame,
+ table,
+ residual: 0.0,
+ scratch: std::cell::UnsafeCell::new(Box::new(Normal::default())),
+ _unsync: std::marker::PhantomData,
+ }
+ }
+
+ #[allow(unused)]
+ pub fn reference(shape: Shape) -> Self {
+ Self::new(shape, 0.0, true)
+ }
+
+ pub fn standard(shape: Shape) -> Self {
+ Self::new(shape, 1e-7, false)
+ }
+
+ pub fn tap_at(&self, u: f64) -> QuadJetResult {
+ self.integrate(u)
+ }
+
+ fn integrate(&self, u: f64) -> QuadJetResult {
+ let frame = &self.frame;
+ let Frame { beta, g, .. } = *frame;
+ let tau = TAU * u.abs() / beta;
+ let rel = relative(self.tol);
+
+ let Membership {
+ roots,
+ weights,
+ smooth,
+ partner,
+ } = self.table.roots_at(tau, frame);
+
+ let mut saddles: [Saddle; MAX_G] = [Saddle::default(); MAX_G];
+ for i in 0..g {
+ saddles[i] = Saddle::new(roots[i], frame);
+ }
+ let mut active = [0usize; MAX_G];
+ let mut live = 0;
+ for i in 0..g {
+ if weights[i].abs() > LIVE {
+ active[live] = i;
+ live += 1;
+ }
+ }
+ let active = &active[..live];
+
+ // Every scale carries `e^{βΦ}`. Dividing the dominant saddle's exponent out leaves
+ // ratios near unity for everything downstream to compare, and it goes back on once at
+ // the end.
+ let log_scale = active
+ .iter()
+ .map(|&i| beta * saddles[i].phi.re)
+ .fold(f64::NEG_INFINITY, f64::max);
+
+ let mut scales = [[Complex64::default(); 2]; MAX_G];
+ for i in 0..g {
+ scales[i] = saddles[i].scales(frame, log_scale);
+ }
+
+ let singulants = Singulants::new(&saddles, frame);
+ let adj = singulants.adjacent();
+
+ // Sizes are read off `ψ` alone, since `ψ` is the channel the accuracy is owed to.
+ let mut amps = [0.0_f64; MAX_G];
+ for i in 0..g {
+ amps[i] = saddles[i].amplitude(frame, scales[i][0]);
+ }
+
+ let dominant = active
+ .iter()
+ .map(|&i| amps[i] * weights[i].abs())
+ .fold(0.0_f64, f64::max);
+
+ let mut psi_re: Accumulator = Accumulator::default();
+ let mut psi_im: Accumulator = Accumulator::default();
+ let mut d_re: Accumulator = Accumulator::default();
+ let mut d_im: Accumulator = Accumulator::default();
+ let mut residual = 0.0_f64;
+
+ // The borrow lives to the end of the tap and nothing else in the call tree reaches the
+ // cell, so no second reference to it exists.
+ let normal: &mut Normal = unsafe { &mut *self.scratch.get() };
+ let mut cost = Cost::default();
+
+ // What each saddle came back with, and whether a traced contour produced it.
+ let mut got: [Option<(Terms, bool)>; MAX_G] = std::array::from_fn(|_| None);
+
+ for &i in active {
+ let s = &saddles[i];
+ let w = weights[i];
+ let seen = singulants.from(i);
+ let scale = scales[i];
+
+ // The bar is `rel` of the largest contribution any saddle makes to `ψ`, divided back
+ // through this saddle's weight because everything in here is still pre-weight.
+ let target = rel * dominant / w.abs();
+
+ // The nearest singulant that can actually reach saddle `i` is both where its series
+ // turns and the floor `e^{-r*}` it can never go below. A shadowed saddle sits
+ // closer in `|ΔΦ|` without being the singularity the expansion runs into.
+ let mut r_star = f64::INFINITY;
+ for j in 0..g {
+ if adj[i] & (1 << j) != 0 {
+ r_star = r_star.min(seen[j].norm());
+ }
+ }
+
+ // The bar belongs to the dominant saddle, and a suppressed one meets it with fewer
+ // digits of its own. This is what saddle `i` owes in its own units.
+ let local_bar = (amps[i] / target).ln();
+
+ // The skip below is really the jet's own opinion that a saddle is too small to
+ // bother with, read off its leading Watson term. Reference mode has no jet, so it
+ // owes that opinion nothing: every active saddle gets integrated, cold, by
+ // quadrature, and stands or falls on what quadrature itself finds.
+ if !self.quadrature_only && local_bar <= 1.0 {
+ residual += amps[i] * w.abs();
+ continue;
+ }
+
+ let resolved = if self.quadrature_only {
+ let handoff = Handoff {
+ normal: None,
+ degree: 0,
+ inner: 0.0,
+ outer: 0.0,
+ };
+ // Nothing was subtracted, so the path owes the whole saddle in both the density
+ // it needs and the distance it walks.
+ let quad = s.quadrature(frame, local_bar, rel, scale, target, seen, &handoff);
+ cost += quad.cost;
+ (quad.terms, true)
+ } else {
+ // The pair's least term sits at the partner's singulant, which is not the nearest
+ // one the screen found.
+ let pin = partner[i].map(|k| seen[k].norm().ceil() as usize);
+
+ let mut jet = s.jet(frame, scale, target, r_star, local_bar, pin, normal);
+ cost += jet.cost;
+
+ // A missed bar buys more series before it buys any nodes, but only where the
+ // first pass stopped on the search rather than on its own turn. A pass that
+ // watched its terms turn or already reached the cap has nothing further to sell,
+ // and asking again reproduces it exactly.
+ if jet.terms.residual > target && !jet.exhausted {
+ let deeper = s.deepen(frame, scale, target, r_star, normal);
+ cost += deeper.cost;
+ jet = deeper;
+ }
+
+ if jet.terms.residual > target {
+ // The series speaks inside its own disk, so that is what bounds the
+ // subtraction. How far the path walked is answered by the moments.
+ let wall = branch_wall(seen, beta);
+ let degree = (2 * jet.reached).min(wall_degree(wall, beta, local_bar, rel));
+
+ let width = trust_width(degree, rel);
+ normal.extend(s, frame, width);
+ let inner = if width >= trust_orders(rel) + degree {
+ SERIES_TRUST * wall
+ } else {
+ 0.0
+ };
+
+ let handoff = Handoff {
+ normal: Some(&normal),
+ degree,
+ inner,
+ outer: PREDICT_TRUST * wall,
+ };
+
+ let quad = s.quadrature(frame, local_bar, rel, scale, target, seen, &handoff);
+ cost += quad.cost;
+
+ let moved = (quad.terms.value[0] - jet.terms.value[0]).norm();
+ cost.quad_gain = cost.quad_gain.max(moved / target);
+
+ (quad.terms, true)
+ } else {
+ (jet.terms, false)
+ }
+ };
+
+ got[i] = Some(resolved);
+ }
+
+ // The smoothing splits one contribution across a pair, so it holds only where both
+ // members answered from a truncated series. A traced contour is exact and its partner
+ // has no half to supply.
+ for &i in active {
+ let Some((terms, traced)) = &got[i] else {
+ continue;
+ };
+ let paired = partner[i].is_some_and(|k| got[k].as_ref().is_some_and(|g| !g.1));
+ let w = if !traced && paired {
+ smooth[i]
+ } else {
+ weights[i]
+ };
+
+ residual += terms.residual * w.abs();
+ let pv = terms.value[0] * w;
+ let qv = terms.value[1] * w;
+
+ psi_re.add(pv.re);
+ psi_im.add(pv.im);
+ d_re.add(qv.re);
+ d_im.add(qv.im);
+ }
+
+ // a_{β,γ} = 2(eγ/β)^{β/γ}
+ let unscale = 2.0 * log_scale.exp();
+ let psi = Complex64::new(psi_re.sum(), psi_im.sum()) * unscale;
+ let d = Complex64::new(d_re.sum(), d_im.sum()) * unscale;
+ let residual = residual * unscale;
+
+ if u < 0.0 {
+ QuadJetResult {
+ psi: psi.conj(),
+ d: d.conj(),
+ residual,
+ cost,
+ }
+ } else {
+ QuadJetResult {
+ psi,
+ d,
+ residual,
+ cost,
+ }
+ }
+ }
+}
+
+/// The steepest-descent curvature at a saddle, carrying the orientation the traced contour is
+/// walked in.
+#[derive(Clone, Copy, Default)]
+struct Descent(Complex64);
+
+impl Descent {
+ fn new(raw: Complex64) -> Self {
+ let flip = if raw.re.abs() > DESCENT_AXIS_TIE * raw.norm() {
+ raw.re < 0.0
+ } else {
+ raw.im < 0.0
+ };
+ Self(if flip { -raw } else { raw })
+ }
+}
+
+/// Where a Newton solve is allowed to stop and what it is allowed to spend, both read off the
+/// accuracy the caller asked for.
+#[derive(Clone, Copy)]
+struct Solve {
+ step_tol: f64,
+ iters: usize,
+}
+
+impl Solve {
+ fn new(rel: f64) -> Self {
+ let step_tol = NEWTON_TOL_FACTOR * rel;
+ // Newton doubles its correct digits, so the passes are the log of the digits.
+ let iters = step_tol.recip().ln().log2().ceil() as usize + NEWTON_SLACK;
+ Self { step_tol, iters }
+ }
+}
+
+/// A root of the saddle condition, carrying the numbers every later step reads off it.
+#[derive(Clone, Copy, Default)]
+struct Saddle {
+ q: Complex64,
+ b: Complex64,
+ phi: Complex64,
+ /// The curvature at the saddle, branch fixed so that `x` runs up the valley the contour
+ /// arrives on.
+ s0: Descent,
+ /// `(B+1)/γ`, the coefficient the `e^{γv}` term of the phase carries.
+ bp1: Complex64,
+ gi: i32,
+}
+
+impl Saddle {
+ /// The phase `Φ = ln q + B(1 - 1/γ)` at a root, where the saddle condition collapses
+ /// `q^γ - 1` into `B = iτq`. Integer power rather than `powf`, since the principal branch
+ /// of `q^γ` parts company with the polynomial over most of the root set.
+ fn new(q: Complex64, frame: &Frame) -> Self {
+ let Frame { gamma, gi, .. } = *frame;
+ let b = q.powi(gi) - 1.0;
+ let phi = q.ln() + b * (1.0 - 1.0 / gamma);
+
+ Saddle {
+ q,
+ b,
+ phi,
+ s0: Descent::new((-(b * (1.0 - gamma) - gamma)).sqrt()),
+ bp1: (b + 1.0) / gamma,
+ gi,
+ }
+ }
+
+ /// The cheap approach to a saddle, Watson's lemma on the series `Normal` carries.
+ ///
+ /// The order is predicted before the first coefficient exists, since the singulant `r_star`
+ /// says where the series turns and the bar says where its terms fall under notice. A
+ /// prediction that runs short is doubled until it holds or reaches the cap, and each retry
+ /// costs only the orders the series did not already have.
+ fn jet(
+ &self,
+ frame: &Frame,
+ scales: [Complex64; 2],
+ target: f64,
+ r_star: f64,
+ bar: f64,
+ pin: Option,
+ normal: &mut Normal,
+ ) -> Expansion {
+ normal.seed(self, frame);
+
+ let n_cap = cap_for(r_star);
+ let mut cost = Cost {
+ jet_saddles: 1,
+ ..Default::default()
+ };
+
+ // The order belongs to the pair, so the search that finds a bar has nothing to look for.
+ if let Some(n) = pin {
+ let n = n.clamp(JET_SETTLE_FLOOR, JET_ORDER / 2);
+ normal.extend(self, frame, 2 * n);
+ let pass = self.jet_sum(frame, scales, target, n, false, normal);
+ cost += pass.cost;
+ return Expansion {
+ terms: pass.terms,
+ reached: pass.reached,
+ exhausted: pass.spent,
+ cost,
+ };
+ }
+
+ // A series whose own floor sits under its own bar is handing its polynomial to
+ // quadrature no matter how far it climbs. There is nothing to search for, so build it
+ // once at the cap and let the caller trace the rest.
+ let mut n_max = if r_star <= bar {
+ n_cap
+ } else {
+ predict_order(bar, r_star).clamp(JET_SETTLE_FLOOR, n_cap)
+ };
+
+ loop {
+ normal.extend(self, frame, 2 * n_max);
+ let pass = self.jet_sum(frame, scales, target, n_max, true, normal);
+ cost += pass.cost;
+ if pass.settled || pass.spent || n_max == n_cap {
+ return Expansion {
+ terms: pass.terms,
+ reached: pass.reached,
+ exhausted: pass.spent || n_max == n_cap,
+ cost,
+ };
+ }
+ n_max = (2 * n_max).min(n_cap);
+ }
+ }
+
+ /// Everything the series still has, spent before any node is. An order is one convolution
+ /// against coefficients that already exist, while a node is a Newton solve down a valley
+ /// that may have to be walked twice, so a saddle that missed its bar asks the series for the
+ /// rest before it asks the path for anything. Often the rest is enough and no path is
+ /// traced. When it is not, the deeper polynomial is what the path gets to stand on and the
+ /// shortfall it has to cover is smaller by whatever those orders bought.
+ fn deepen(
+ &self,
+ frame: &Frame,
+ scales: [Complex64; 2],
+ target: f64,
+ r_star: f64,
+ normal: &mut Normal,
+ ) -> Expansion {
+ let n_cap = cap_for(r_star);
+ normal.extend(self, frame, 2 * n_cap);
+ let pass = self.jet_sum(frame, scales, target, n_cap, false, normal);
+ Expansion {
+ terms: pass.terms,
+ reached: pass.reached,
+ cost: pass.cost,
+ exhausted: true,
+ }
+ }
+
+ /// The series at one order. Each even coefficient meets its Gaussian moment, and the two
+ /// channels differ only in which `h` they read.
+ ///
+ /// The envelope of the `ψ` terms is what decides where the sum ends. `dψ/du` is accumulated
+ /// over exactly the orders `ψ` accepted, so it neither prolongs the sum nor cuts it short.
+ /// Ending on the mathematics, having diverged or crossed under the bar or run into roundoff,
+ /// means the series has said everything it is going to say.
+ fn jet_sum(
+ &self,
+ frame: &Frame,
+ scales: [Complex64; 2],
+ target: f64,
+ n_max: usize,
+ stop_at_bar: bool,
+ normal: &Normal,
+ ) -> Pass {
+ let beta = frame.beta;
+ let scale_abs = scales[0].norm();
+
+ let mut moment = (TAU / beta).sqrt();
+ let mut running = [Complex64::default(); 2];
+ let mut last = 0.0_f64;
+
+ // The envelope decides where the series turned and the accepted term is what the series
+ // still owes. An order only becomes a truncation when the envelope improved, which
+ // means both it and its predecessor are small, so the accepted term is never a zero of
+ // the oscillation standing in for the remainder.
+ let mut best = [Complex64::default(); 2];
+ let mut best_env = f64::INFINITY;
+ let mut best_term = f64::INFINITY;
+ let mut reached = 0usize;
+ let mut descents = 0usize;
+
+ let mut spent = false;
+ let mut met = false;
+ let mut rises = 0u32;
+
+ for n in 0..=n_max {
+ let term = [normal.h[0][2 * n] * moment, normal.h[1][2 * n] * moment];
+ let size = scale_abs * term[0].norm();
+
+ // A conjugate pair of singulants makes the terms oscillate, which is forced at
+ // `τ = 0` where every `Δ` is imaginary, so a single small term is a zero of the
+ // oscillation rather than the remainder. The envelope is what decays.
+ let env = size.max(last);
+ last = size;
+
+ running[0] += term[0];
+ running[1] += term[1];
+
+ if env < best_env {
+ best_env = env;
+ best_term = size;
+ best = running;
+ reached = n;
+ rises = 0;
+ descents += 1;
+
+ // Meeting the bar ends a pass that was sent to find the bar, once the envelope
+ // has descended far enough to be an envelope rather than a slow zero of the
+ // oscillation. A pass building the shape a path will stand on notes the
+ // crossing and keeps climbing, since the orders above are ones the path does not
+ // have to resolve. Roundoff ends both and answers to no floor, since a sum that
+ // has lost its bits gains nothing from more terms.
+ if env <= target && descents >= JET_SETTLE_FLOOR {
+ met = true;
+ if stop_at_bar {
+ break;
+ }
+ }
+
+ if env <= EPS * scale_abs * running[0].norm() {
+ spent = true;
+ met = true;
+ break;
+ }
+ } else {
+ rises += 1;
+ // Terms oscillate and alias within an envelope, so the turn is confirmed over
+ // several orders before the tail is believed.
+ if rises >= TURN_CONFIRM {
+ spent = true;
+ break;
+ }
+ }
+
+ moment *= (2 * n + 1) as f64 / beta;
+ }
+
+ let value = [scales[0] * best[0], scales[1] * best[1]];
+ Pass {
+ terms: Terms {
+ // No channel can claim more digits than the partial sum carries, and the traced
+ // path is held to the same floor.
+ residual: best_term.max(EPS * value[0].norm()),
+ value,
+ },
+ reached,
+ settled: met,
+ spent,
+ cost: Cost {
+ jet_passes: 1,
+ jet_orders: reached as u32,
+ jet_depth: reached as u32,
+ ..Default::default()
+ },
+ }
+ }
+
+ /// The expensive approach to a saddle, a trapezoid along its traced steepest-descent path.
+ ///
+ /// Node density is a question about the neighbors and nothing else. Aliasing folds in
+ /// whatever feature sits `gap` off the path, carrying the size that feature already has, and
+ /// the trapezoid buries it as `e^{-2π·gap·density}`. The rate in that exponent is geometry
+ /// and the model knows it. The amplitude in front of it is the thing the model only guesses
+ /// at, and it is the guess that goes wrong wherever two saddles are close to trading places.
+ ///
+ /// So the amplitude gets measured instead. A coarse anchor level is placed where the feature
+ /// is still standing in the answer, and the difference between it and a finer level names the
+ /// amplitude the model was standing in for. Each further level is placed where the last
+ /// difference says the bar is met, and once two differences exist the rate becomes measured
+ /// too. Any of those levels may already be the whole answer, so the passes that calibrate
+ /// the model are the same passes that can retire it.
+ ///
+ /// The path is one contour and it carries no `m`, so the placement is decided by what `ψ`
+ /// still owes and `dψ/du` is read off the same nodes.
+ ///
+ /// How far the path walks is a different question with a different answer. The reach belongs
+ /// to the bar alone, and where a neighboring saddle sits on this path the trace runs out of
+ /// valley and stops on its own. What it never reached is charged to the endpoint and
+ /// reported, never handed to the placement, since no density buys back a piece of contour
+ /// that was never walked.
+ fn quadrature(
+ &self,
+ frame: &Frame,
+ bar: f64,
+ rel: f64,
+ scales: [Complex64; 2],
+ target: f64,
+ seen: &[Complex64],
+ hand: &Handoff,
+ ) -> Priced {
+ // Each neighbor is a square-root branch point of the inverse map at `x_c = √(-2Δ/β)`.
+ // Its distance off the path is the aliasing gap the density answers to, and its modulus
+ // is where the map's own series stops converging. A neighbor sitting below this one
+ // with equal `Im Φ` puts that point on the path itself, which is the configuration a
+ // trace runs out of valley in.
+
+ // Each neighbor is a square-root branch point of the inverse map at `x_c = √(-2Δ/β)`,
+ // and what the density answers to is how far that point sits off the path. One standing
+ // above this saddle enters amplified and charges full freight, while one already
+ // suppressed is credited only partly, since the fold point sits nearer than the
+ // neighbor's own center and sees less of that decay.
+ let mut gap = 1.0_f64;
+ let mut lift = 0.0_f64;
+ let mut want = 0.0_f64;
+ for &delta in seen {
+ let t = (-2.0 * delta).sqrt().im.abs();
+ if t <= GAP_FLOOR {
+ continue;
+ }
+ let l = if delta.re > 0.0 {
+ delta.re
+ } else {
+ LIFT_CREDIT * delta.re
+ };
+ let need = (bar + l).max(0.0) / t;
+ if need > want {
+ want = need;
+ gap = t;
+ lift = l;
+ }
+ }
+ // Aliasing folds the neighbor onto the path carrying the size the neighbor already has,
+ // and a polynomial is entire, so subtracting one leaves that fold exactly where it was.
+ // Density answers to the whole saddle no matter how well the series did. So does the
+ // distance, since the moments put the polynomial back over the whole line and a walk
+ // that stops early owes the difference.
+ let reach = reach_for(bar);
+ let model_rate = TAU * gap;
+ let ceiling = (QUAD_MAX_NODES as f64 / (2.0 * reach)).max(QUAD_MIN_DENSITY);
+ // The weight has no singularity for a neighbor term to find, and it is not band limited
+ // either. `∫e^{-x²/2}` trapezoids to `e^{-2π²·density²}`, so `bar` e-folds of that is a
+ // floor no branch point speaks to.
+ let ideal = (((bar + lift).max(0.0) + PLACE_MARGIN_EFOLDS) / model_rate)
+ .max(reach / TAU)
+ .clamp(QUAD_MIN_DENSITY, ceiling);
+
+ let value = |lv: &Level, m: usize| scales[m] * (lv.resid[m] + lv.moments[m]);
+ let spread = |a: &Level, b: &Level| {
+ (scales[0] * (a.resid[0] + a.moments[0] - b.resid[0] - b.moments[0])).norm()
+ };
+
+ let mut cost = Cost::default();
+
+ // The anchor is placed by the suppression and not by the answer. A few e-folds of decay
+ // is what makes the gap between two levels a measurement of the neighbor rather than a
+ // measurement of the anchor's own coarseness, and an extrapolation off the flat stretch
+ // below onset always lands short. Where the answer itself sits below onset the anchor
+ // keeps its place and the finer level is lifted to clear it.
+ let onset = ANCHOR_EFOLDS / model_rate;
+ let anchor_density = onset
+ .max(CALIBRATE_NODES / reach)
+ .clamp(QUAD_MIN_DENSITY, ceiling);
+ let fine_density = ideal.max(PLACE_STEP * anchor_density).min(ceiling);
+
+ let anchor = self.trapezoid(frame, reach, anchor_density, rel, hand);
+ cost += anchor.cost;
+
+ let mut level = self.trapezoid(frame, reach, fine_density, rel, hand);
+ cost += level.cost;
+
+ let mut lo = anchor_density;
+ let mut hi = fine_density;
+ let mut err_lo = spread(&level, &anchor);
+ let mut rate = model_rate;
+ let mut carried = f64::INFINITY;
+
+ for _round in 0..PLACE_ROUNDS {
+ // A difference between two levels bounds the error of the coarser one, so what the
+ // finer still carries is that difference decayed across the step between them. The
+ // decay is derated, since the rate is the model's until a second difference exists
+ // and a model that flatters the neighbor should not be allowed to certify on the
+ // strength of that flattery.
+ let bar_abs = target.max(EPS * value(&level, 0).norm());
+ carried = if hi > lo {
+ err_lo * (-CERTIFY_DERATE * rate * (hi - lo)).exp()
+ } else {
+ f64::INFINITY
+ };
+ let short = carried > bar_abs;
+ let place = lo + (err_lo / bar_abs).max(1.0).ln() / rate;
+
+ // A pair that has not yet reached onset is measuring itself, so its difference is no
+ // evidence about either level and the loop buys another regardless of what the
+ // projection claims.
+ if !short && lo >= onset {
+ break;
+ }
+
+ let next = (hi + PLACE_STEP * (place - hi)).min(ceiling);
+ if next <= hi {
+ break;
+ }
+
+ let step = self.trapezoid(frame, reach, next, rel, hand);
+ cost += step.cost;
+ let err_hi = spread(&step, &level);
+
+ // Two consecutive levels name the suppression the path actually gets, which is the
+ // number the model was standing in for. A pair that failed to shrink has hit
+ // roundoff and has nothing left to say, and a rate far from the model's has been
+ // read off terrain the model does not describe, so both leave the job with the model
+ // rather than let one measurement steer the whole placement.
+ let mut measured = f64::NAN;
+ if err_hi > 0.0 && err_lo > err_hi {
+ measured = (err_lo / err_hi).ln() / (hi - lo);
+ rate = measured.clamp(model_rate / RATE_CREDIBLE, model_rate * RATE_CREDIBLE);
+ }
+
+ lo = hi;
+ hi = next;
+ err_lo = err_hi;
+ level = step;
+ }
+
+ cost.quad_density_ratio = hi / ideal;
+ cost.quad_rate_ratio = rate / model_rate;
+
+ // A ceiling-bound pair measured nothing, so the level's own size is the only bound
+ // available.
+ let alias = carried.min(scales[0].norm() * level.resid[0].norm());
+
+ // Each side stopped where its own valley gave out, so the Gaussian is charged twice at
+ // two different edges rather than once at the shorter of them.
+ let width = (TAU / frame.beta).sqrt() / self.s0().norm();
+ let tail = 0.5
+ * width
+ * level
+ .spans
+ .iter()
+ .map(|s| libm::erfc(s / SQRT_2))
+ .sum::();
+
+ let value = [value(&level, 0), value(&level, 1)];
+ let residual = (alias + tail * scales[0].norm()).max(EPS * value[0].norm());
+
+ cost.quad_truncated = !level.full;
+ cost.quad_short = residual > target.max(EPS * value[0].norm());
+
+ Priced {
+ terms: Terms { value, residual },
+ cost,
+ }
+ }
+
+ /// One level. In the normal coordinate the phase is exactly `-x²/2`, so the weight is
+ /// Gaussian by construction and cannot overflow the way a straight segment in `v` does once
+ /// the reach is long enough for `e^{γv}` to climb the neighboring hill. The path carries no
+ /// `m`, so one trace serves both channels.
+ ///
+ /// Each level stands alone at its own density. The inner nodes come from the map's own
+ /// series and the outer ones are traced, and either side may run out of valley before the
+ /// reach is spent, so the sum stops there and reports the span it actually covered, which is
+ /// what the endpoint charge is built on.
+ fn trapezoid(
+ &self,
+ frame: &Frame,
+ reach: f64,
+ density: f64,
+ rel: f64,
+ hand: &Handoff,
+ ) -> Level {
+ let beta = frame.beta;
+ let h = 1.0 / (density * beta.sqrt());
+ let n = (reach * density).round().max(1.0) as usize;
+
+ // At the saddle `x` and `g'` vanish together and the slope `-x/g'(v)` goes to `1/s0`.
+ let apex = (Complex64::default(), self.s0().inv());
+
+ let mut acc = [
+ (Accumulator::::default(), Accumulator::::default()),
+ (Accumulator::::default(), Accumulator::::default()),
+ ];
+
+ let mut tally = |x: f64, f: [Complex64; 2]| {
+ let gauss = (-0.5 * beta * x * x).exp();
+ let f1 = gauss * f[0];
+ let f2 = gauss * f[1];
+ acc[0].0.add(f1.re);
+ acc[0].1.add(f1.im);
+ acc[1].0.add(f2.re);
+ acc[1].1.add(f2.im);
+ };
+
+ // The node as a traced point gives it, the whole integrand less the whole subtracted
+ // polynomial. Past the trust radius this is the only form available.
+ let traced = |x: f64, v: Complex64, slope: Complex64| {
+ let ev = v.exp();
+ [
+ ev * slope - hand.poly(0, x),
+ ev * ev * slope - hand.poly(1, x),
+ ]
+ };
+
+ tally(
+ 0.0,
+ hand.tail(0.0)
+ .unwrap_or_else(|| traced(0.0, apex.0, apex.1)),
+ );
+
+ let mut walked = 0u32;
+ let mut summed = 0u32;
+ let mut spans = [0.0_f64; 2];
+ let mut full = true;
+
+ let mut seed = self.q.re.to_bits() | 1;
+
+ for (which, side) in [1.0_f64, -1.0].into_iter().enumerate() {
+ let mut at = apex;
+ let mut splits = 1u32;
+ let mut last = 0usize;
+ let mut summing = true;
+ for j in 1..=n {
+ let x0 = side * (j - 1) as f64 * h;
+ let x1 = side * j as f64 * h;
+
+ if summing {
+ if let Some(f) = hand.tail(x1) {
+ tally(x1, f);
+ summed += 1;
+ last = j;
+ continue;
+ }
+ if let Some(state) = hand.at(x0) {
+ at = state;
+ }
+ summing = false;
+ }
+
+ if let Some((guess, slope)) = hand.predict(x1) {
+ let allow = PREDICT_DRIFT * slope.norm() * h;
+ let solve = Solve::new(rel);
+ if let Some(next) = self.close(guess, allow, x1, at.1, solve) {
+ at = next;
+ walked += 1;
+ tally(x1, traced(x1, at.0, at.1));
+ last = j;
+ continue;
+ }
+ }
+
+ if let Some(next) = self.probe(at, x0, x1, rel, &mut seed) {
+ at = next;
+ walked += 1;
+ tally(x1, traced(x1, at.0, at.1));
+ last = j;
+ continue;
+ }
+
+ match self.walk(at, x0, x1, rel, &mut splits) {
+ Some(next) => at = next,
+ None => {
+ break;
+ }
+ }
+ walked += 1;
+ tally(x1, traced(x1, at.0, at.1));
+ last = j;
+ }
+ full &= last == n;
+ spans[which] = last as f64 / density;
+ }
+
+ drop(tally);
+
+ let moments = match hand.normal {
+ Some(normal) => normal.moments_over(beta, hand.degree, spans),
+ None => [Complex64::default(); 2],
+ };
+
+ Level {
+ resid: [
+ Complex64::new(acc[0].0.sum(), acc[0].1.sum()) * h,
+ Complex64::new(acc[1].0.sum(), acc[1].1.sum()) * h,
+ ],
+ spans,
+ moments,
+ full,
+ cost: Cost {
+ quad_paths: 1,
+ quad_nodes: walked,
+ quad_series: summed,
+ ..Default::default()
+ },
+ }
+ }
+
+ /// Newton on `g(v) = -x²/2` from a guess, with the drift the caller is willing to see.
+ ///
+ /// Newton doubles its digits every pass, so a step that stops shrinking has found the floor
+ /// the arithmetic allows rather than failing to arrive. Both endings count as arrival while
+ /// the last step is small. Landing far from the guess means the iteration crossed onto a
+ /// neighboring saddle's sheet, which is a wrong node rather than an inaccurate one.
+ fn close(
+ &self,
+ guess: Complex64,
+ allow: f64,
+ x1: f64,
+ from: Complex64,
+ solve: Solve,
+ ) -> Option<(Complex64, Complex64)> {
+ let mut w = guess;
+ let target = Complex64::new(-0.5 * x1 * x1, 0.0);
+
+ let mut arrived = false;
+ let mut gp = Complex64::default();
+ let mut prev = f64::INFINITY;
+ for _ in 0..solve.iters {
+ let (gv, gpv) = self.g(w);
+ let step = (gv - target) / gpv;
+ w -= step;
+ gp = gpv;
+
+ let size = step.norm();
+ if size < solve.step_tol {
+ arrived = true;
+ break;
+ }
+ // A step that stopped halving has reached the floor the cancellation in `g` allows.
+ // Where that floor sits is a property of `b` and `s0` rather than of `w`, so arrival
+ // is read off the halving and the landing answers to `allow` and the slope gate.
+ if size > 0.5 * prev {
+ arrived = true;
+ break;
+ }
+ prev = size;
+ }
+
+ let slope = -x1 / gp;
+ let drift = (w - guess).norm();
+ let cos = (slope * from.conj()).re / (slope.norm() * from.norm());
+ if !arrived || drift > allow || cos <= SHEET_COS {
+ return None;
+ }
+ Some((w, slope))
+ }
+
+ /// One step along the path that `dv/dx = -x/g'(v)` predicts, closed by Newton. The tangent
+ /// is only as good as the step is short, so the drift it allows is the step it took.
+ fn advance(
+ &self,
+ v: Complex64,
+ slope: Complex64,
+ x0: f64,
+ x1: f64,
+ rel: f64,
+ ) -> Option<(Complex64, Complex64)> {
+ let h = x1 - x0;
+ let allow = 4.0 * slope.norm() * h.abs() + 0.25;
+ let solve = Solve::new(rel);
+ self.close(v + slope * h, allow, x1, slope, solve)
+ .filter(|(w, _)| (w - v).norm() <= allow)
+ }
+
+ /// Subdivides a step until the path stays in its own valley, and reports the give-up rather
+ /// than handing back where it got to. A node quietly placed short of its own `x` is worse
+ /// than no node.
+ ///
+ /// Difficulty here is a property of the terrain and not of the node, and it only grows as
+ /// the walk leaves the saddle and closes on a neighbor. So the split count that worked last
+ /// time is where the next node starts. Climbing from one at every node pays the whole climb
+ /// again along the stretch where the valley is tightest, which is exactly the stretch
+ /// carrying the most nodes.
+ fn walk(
+ &self,
+ from: (Complex64, Complex64),
+ x0: f64,
+ x1: f64,
+ rel: f64,
+ splits: &mut u32,
+ ) -> Option<(Complex64, Complex64)> {
+ loop {
+ let sub = (x1 - x0) / *splits as f64;
+ let mut at = from;
+ let mut ok = true;
+ for k in 1..=*splits {
+ let a = x0 + sub * (k - 1) as f64;
+ let b = x0 + sub * k as f64;
+ match self.advance(at.0, at.1, a, b, rel) {
+ Some(next) => at = next,
+ None => {
+ ok = false;
+ break;
+ }
+ }
+ }
+ if ok {
+ return Some(at);
+ }
+ if *splits > 1 << TRACE_MAX_SPLIT {
+ return None;
+ }
+ *splits *= 2;
+ }
+ }
+
+ /// A scatter of starting points where nothing can say where the path went.
+ ///
+ /// Newton lands on whichever sheet its guess sits nearest, so the guess is the whole
+ /// question and subdivision only answers it by accident. A proposal costs one solve and
+ /// three dot products against the gates `close` already applies, and the shortest landing
+ /// wins. The first proposal is the tangent itself.
+ fn probe(
+ &self,
+ from: (Complex64, Complex64),
+ x0: f64,
+ x1: f64,
+ rel: f64,
+ seed: &mut u64,
+ ) -> Option<(Complex64, Complex64)> {
+ let step = from.1 * (x1 - x0);
+ let spread = PROBE_SPREAD * step.norm();
+ let base = from.0 + step;
+ let leash = PROBE_REACH * step.norm() + spread;
+ let solve = Solve::new(rel);
+
+ for k in 0..PROBE_TRIES {
+ let (guess, allow) = if k == 0 {
+ (base, step.norm())
+ } else {
+ let off = spread * kick(seed);
+ (base + off, off.norm() + step.norm())
+ };
+ let Some(next) = self.close(guess, allow, x1, from.1, solve) else {
+ continue;
+ };
+ if (next.0 - from.0).norm() > leash {
+ continue;
+ }
+ return Some(next);
+ }
+ None
+ }
+
+ /// This saddle's prefactor for each channel, with the dominant `e^{βΦ}` already divided out
+ /// so that the caller can restore it once at the end.
+ fn scales(&self, frame: &Frame, log_scale: f64) -> [Complex64; 2] {
+ let base = (self.phi * frame.beta - log_scale).exp();
+ [base * self.q, base * self.q * self.q]
+ }
+
+ /// The phase `g(v) = v + B(e^v - 1) - ((B+1)/γ)(e^{γv} - 1)` measured from the saddle, along
+ /// with the derivative every Newton iteration of every node asks for. `e^{γv}` is an
+ /// integer power of `e^v`, so one transcendental serves both.
+ fn g(&self, v: Complex64) -> (Complex64, Complex64) {
+ let ev = v.exp();
+ let egv = ev.powi(self.gi);
+ (
+ v + self.b * (ev - 1.0) - self.bp1 * (egv - 1.0),
+ 1.0 + self.b * ev - (self.b + 1.0) * egv,
+ )
+ }
+
+ /// The leading Watson term `|scale| √(2π/β)/|s₀|`, which is what this saddle contributes
+ /// before any correction and what its bar is measured against. The Gaussian width belongs
+ /// in it, since a saddle with small `Φ''` is wide and outweighs its prefactor.
+ fn amplitude(&self, frame: &Frame, scale: Complex64) -> f64 {
+ scale.norm() * (TAU / frame.beta).sqrt() / self.s0().norm()
+ }
+
+ /// The resolved curvature, the one number the whole normal coordinate stands on.
+ fn s0(&self) -> Complex64 {
+ self.s0.0
+ }
+}
+
+/// The order the series is predicted to need, in the index the moments actually carry. Terms go
+/// like `Γ(n)/r*^n`, so a bar of `bar` e-folds asks for the `n` solving `n(1 + ln(r*/n)) = bar`.
+/// The map is increasing and the seed sits above the root, so the iteration walks down onto it
+/// and stopping early lands on the generous side.
+fn predict_order(bar: f64, r_star: f64) -> usize {
+ let mut n = bar.max(1.0);
+ for _ in 0..3 {
+ n = bar / ((r_star / n).max(1.0).ln() + 1.0);
+ }
+ n.ceil() as usize
+}
+
+/// Where the search is allowed to stop asking. The singulant says where the terms turn, the
+/// settle floor keeps a short singulant from capping the search under the order a bar can be
+/// read at, and `JET_SLOTS` is the hard wall.
+fn cap_for(r_star: f64) -> usize {
+ ((JET_OVERSHOOT * r_star).ceil() as usize)
+ .max(JET_SETTLE_FLOOR)
+ .min(JET_ORDER / 2)
+}
+
+/// What the jet leaves behind for the path to stand on. The series carries the shape the
+/// integrand has near the saddle, so the trapezoid walks only what is left once that shape comes
+/// out, and the moments of the same truncation put it back exactly.
+///
+/// The caller owes us a degree the path's own footprint covers, since a term of degree `k` peaks
+/// at `√k` and one peaking outside the walk would be subtracted where the path is not and added
+/// back over the whole line.
+///
+/// One degree serves both channels, since the truncation is a property of how far the path
+/// walked and the path is the same curve for both.
+struct Handoff<'a> {
+ /// `None` means no series ran for this saddle at all, and the trapezoid should integrate the
+ /// bare integrand with nothing subtracted, which is what reference mode asks for on every
+ /// saddle.
+ normal: Option<&'a Normal>,
+ /// Degree in `x`, twice the order the series reached. Unused when `normal` is `None`.
+ degree: usize,
+ /// How far out the jet series places nodes on its own.
+ inner: f64,
+ /// How far out it is still worth asking the series where the path went.
+ outer: f64,
+}
+
+impl Handoff<'_> {
+ fn poly(&self, m: usize, x: f64) -> Complex64 {
+ let Some(normal) = self.normal else {
+ return Complex64::default();
+ };
+ let c = &normal.h[m];
+ let mut acc = c[self.degree];
+ for k in (0..self.degree).rev() {
+ acc = acc * x + c[k];
+ }
+ acc
+ }
+
+ /// Both channels inside the trust radius. The integrand and the subtracted polynomial are
+ /// the same series truncated at two places, so their difference is the coefficient tail and
+ /// is formed as one. The leading `x^{degree+1}` is the whole reason that difference is
+ /// small, so it multiplies in once rather than being discovered by cancellation.
+ fn tail(&self, x: f64) -> Option<[Complex64; 2]> {
+ let normal = self.normal?;
+ if x.abs() >= self.inner {
+ return None;
+ }
+ let lead = x.powi(self.degree as i32 + 1);
+ let mut out = [Complex64::default(); 2];
+ for m in 0..2 {
+ let c = &normal.h[m];
+ let mut acc = c[normal.width];
+ for k in (self.degree + 1..normal.width).rev() {
+ acc = acc * x + c[k];
+ }
+ out[m] = acc * lead;
+ }
+ Some(out)
+ }
+
+ /// Where the series says the path is at `x`, and the slope it arrives with. Two radii read
+ /// this. Inside `inner` it is the node, and out to `outer` it is only the guess Newton
+ /// starts from, which is a weaker thing to ask and so reaches farther.
+ fn at(&self, x: f64) -> Option<(Complex64, Complex64)> {
+ let normal = self.normal?;
+ let mut v = normal.v[normal.width];
+ let mut w = normal.w[normal.width];
+ for k in (0..normal.width).rev() {
+ v = v * x + normal.v[k];
+ w = w * x + normal.w[k];
+ }
+ Some((v, w))
+ }
+
+ /// The guess for a node the series cannot place but can still find. Newton converges to
+ /// whichever root of `g(v) = -x²/2` it starts nearest, and every failure of the tangent
+ /// predictor is a landing on a neighbor's sheet, so a guess already in the right valley is
+ /// worth more than any amount of subdivision.
+ fn predict(&self, x: f64) -> Option<(Complex64, Complex64)> {
+ if x.abs() >= self.outer {
+ return None;
+ }
+ self.at(x)
+ }
+}
+
+/// The integrand in the normal coordinate, carried as a series in `x`.
+///
+/// The saddle is where `g'` vanishes, so `P = g'` has no constant term and `P = x·P̃`. That
+/// missing term is what makes the whole scheme go. A convolution that would otherwise close on
+/// itself at order `k` instead drops its own leading term, and the order-`k` coefficient falls
+/// out against lower ones.
+///
+/// Every recurrence below reads only what sits beneath it, so a jet that guessed its order too
+/// low extends into the series it already has. Growing to twice the order costs the difference
+/// and nothing more, which is the whole reason for the coordinate change.
+///
+/// `h` is the pair the moments read and the pair a traced path will subtract, held to the full
+/// order rather than the even half, since the path samples both signs of `x` and wants the odd
+/// coefficients the Gaussian throws away.
+struct Normal {
+ /// `e^{v(x)}`.
+ y: [Complex64; JET_SLOTS],
+ /// `k·y_k`, the weight both the `y^γ` split and the `P` convolution read.
+ my: [Complex64; JET_SLOTS],
+ /// `y^γ`, kept because `P` reads it at every order and rebuilding it is a convolution.
+ yg: [Complex64; JET_SLOTS],
+ /// `g'` along the path, `P_0 = 0` by construction.
+ p: [Complex64; JET_SLOTS],
+ /// `dv/dx`, the same slope `trapezoid` walks.
+ w: [Complex64; JET_SLOTS],
+ /// `v(x)` itself, the antiderivative of `w` anchored at the saddle.
+ v: [Complex64; JET_SLOTS],
+ /// `e^{v}·dv/dx` and `e^{2v}·dv/dx`, one per channel.
+ h: [[Complex64; JET_SLOTS]; 2],
+ /// The valid prefix of `w` and `h`. `y`, `yg`, and `p` run one order further.
+ width: usize,
+}
+
+impl Default for Normal {
+ fn default() -> Self {
+ Self {
+ y: [Complex64::default(); JET_SLOTS],
+ yg: [Complex64::default(); JET_SLOTS],
+ my: [Complex64::default(); JET_SLOTS],
+ p: [Complex64::default(); JET_SLOTS],
+ w: [Complex64::default(); JET_SLOTS],
+ v: [Complex64::default(); JET_SLOTS],
+ h: [[Complex64::default(); JET_SLOTS]; 2],
+ width: 0,
+ }
+ }
+}
+
+impl Normal {
+ /// Plants the series at the saddle. Order one is the quadratic root of `y₁P₁ = -1`, whose
+ /// branch is the one `s0` already committed to, and everything above it is linear.
+ fn seed(&mut self, s: &Saddle, frame: &Frame) {
+ let y1 = s.s0().inv();
+ self.y[0] = Complex64::new(1.0, 0.0);
+ self.y[1] = y1;
+ self.my[0] = Complex64::default();
+ self.my[1] = y1;
+ self.yg[0] = Complex64::new(1.0, 0.0);
+ self.yg[1] = y1 * frame.gamma;
+ self.p[0] = Complex64::default();
+ self.p[1] = -s.s0();
+ self.w[0] = y1;
+ self.v[0] = Complex64::default();
+ self.h[0][0] = y1;
+ self.h[1][0] = y1;
+ self.width = 0;
+ }
+
+ /// Grows the series to `target`, picking up wherever the last call stopped.
+ fn extend(&mut self, s: &Saddle, frame: &Frame, target: usize) {
+ if target <= self.width {
+ return;
+ }
+ let gamma = frame.gamma;
+ let bp1 = s.b + 1.0;
+ let s0 = s.s0();
+ let lead = self.y[1] * bp1;
+ let gp1 = gamma + 1.0;
+
+ for k in (self.width + 2)..=(target + 1) {
+ let mut wtd = Complex64::default();
+ let mut plain = Complex64::default();
+ for i in 1..k {
+ wtd += self.my[i] * self.yg[k - i];
+ plain += self.y[i] * self.yg[k - i];
+ }
+ let tail = (gp1 * wtd - (k as f64) * plain) / k as f64;
+
+ let mut mid = Complex64::default();
+ for j in 2..k {
+ mid += self.my[k - j + 1] * self.p[j];
+ }
+
+ self.y[k] = (self.y[k - 1] + mid - lead * tail) / ((k + 1) as f64 * s0);
+ self.my[k] = self.y[k] * k as f64;
+ self.yg[k] = self.y[k] * gamma + tail;
+ self.p[k] = self.y[k] * s.b - self.yg[k] * bp1;
+ }
+
+ // The slope inverts `P̃w = -1`, and the two channels follow as products against `y`.
+ for k in (self.width + 1)..=target {
+ let mut acc = Complex64::default();
+ for i in 0..k {
+ acc += self.w[i] * self.p[k - i + 1];
+ }
+ self.w[k] = -acc / self.p[1];
+ self.v[k] = self.w[k - 1] / k as f64;
+
+ let mut h0 = Complex64::default();
+ let mut h1 = Complex64::default();
+ for i in 0..=k {
+ h0 += self.y[i] * self.w[k - i];
+ }
+ self.h[0][k] = h0;
+ for i in 0..=k {
+ h1 += self.y[i] * self.h[0][k - i];
+ }
+ self.h[1][k] = h1;
+ }
+
+ self.width = target;
+ }
+
+ /// `∫ x^k e^{-βx²/2}` over the span a level actually covered, one per channel, against the
+ /// same truncation the path subtracted. Asymmetric spans keep the odd orders, which is why
+ /// `h` runs to full order rather than the even half.
+ ///
+ /// `M_k = ((k-1)M_{k-2} - [x^{k-1}e^{-βx²/2}])/β`
+ fn moments_over(&self, beta: f64, degree: usize, spans: [f64; 2]) -> [Complex64; 2] {
+ let rb = beta.sqrt();
+ let (b, a) = (spans[0] / rb, spans[1] / rb);
+ let (eb, ea) = (
+ (-0.5 * spans[0] * spans[0]).exp(),
+ (-0.5 * spans[1] * spans[1]).exp(),
+ );
+
+ let root = (TAU / beta).sqrt();
+ let mut prev2 = root * (1.0 - 0.5 * (erfc(spans[0] / SQRT_2) + erfc(spans[1] / SQRT_2)));
+ let mut prev1 = (ea - eb) / beta;
+
+ let mut out = [Complex64::default(); 2];
+ for ch in 0..2 {
+ out[ch] += self.h[ch][0] * prev2 + self.h[ch][1] * prev1;
+ }
+
+ let (mut pb, mut pa) = (1.0_f64, 1.0_f64);
+ for k in 2..=degree {
+ pb *= b;
+ pa *= -a;
+ let mk = ((k - 1) as f64 * prev2 - (pb * eb - pa * ea)) / beta;
+ for ch in 0..2 {
+ out[ch] += self.h[ch][k] * mk;
+ }
+ prev2 = prev1;
+ prev1 = mk;
+ }
+ out
+ }
+}
+
+/// `Δ` between every pair of saddles, stored so that `from(i)` is the row saddle `i` reads:
+/// `Δ_i[j] = β(Φ_j - Φ_i)`, the exponent a neighbor `j` enters at when `i` is the one being
+/// evaluated. The self entry is zero, which every consumer screens out by size.
+struct Singulants {
+ d: [Complex64; MAX_G * MAX_G],
+ g: usize,
+}
+
+impl Singulants {
+ fn new(saddles: &[Saddle; MAX_G], frame: &Frame) -> Self {
+ let g = frame.g;
+ let mut d = [Complex64::default(); MAX_G * MAX_G];
+ for i in 0..g {
+ for j in 0..g {
+ d[i * g + j] = (saddles[j].phi - saddles[i].phi) * frame.beta;
+ }
+ }
+ Self { d, g }
+ }
+
+ fn from(&self, i: usize) -> &[Complex64] {
+ &self.d[i * self.g..(i + 1) * self.g]
+ }
+
+ /// Screens the singulants that could set each saddle's truncation order. A saddle lying
+ /// behind a nearer one in the same direction is not the singularity the series runs into,
+ /// and screening too loosely only lowers `r_star`.
+ fn adjacent(&self) -> [u8; MAX_G] {
+ let mut adj = [0u8; MAX_G];
+ for i in 0..self.g {
+ let seen = self.from(i);
+ for k in 0..self.g {
+ if k == i {
+ continue;
+ }
+ let dk = seen[k];
+ let mut shadowed = false;
+ for j in 0..self.g {
+ if j == i || j == k {
+ continue;
+ }
+ let dj = seen[j];
+ let dot = (dk * dj.conj()).re;
+ if dj.norm_sqr() < dk.norm_sqr()
+ && dot > 0.0
+ && dot * dot > ADJ_CONE * ADJ_CONE * dk.norm_sqr() * dj.norm_sqr()
+ {
+ shadowed = true;
+ break;
+ }
+ }
+ if !shadowed {
+ adj[i] |= 1 << k;
+ }
+ }
+ }
+ adj
+ }
+}
+
+/// What the march says at one `τ`. A fractional weight is the remainder of a series stopped at
+/// the pair's least term, so a saddle inside the switching window carries the partner that order
+/// belongs to.
+struct Membership {
+ roots: [Complex64; MAX_G],
+ weights: [f64; MAX_G],
+ partner: [Option; MAX_G],
+ smooth: [f64; MAX_G],
+}
+
+/// Root identity and membership as functions of `τ`, resolved once.
+///
+/// Membership changes only where two saddles exchange dominance, so it has to be marched from
+/// the seed at `τ = 0` rather than evaluated at a point. Nothing in the march depends on `β`,
+/// so it happens at construction and a tap brackets into the result and polishes.
+///
+/// Nodes sit in `ln(1 + τ)`, where the roots move slowly. `du/dτ = iu/(γu^{γ-1} - iτ)` carries
+/// the double-root condition in its denominator, which for `γ ≥ 3` never comes due on the real
+/// `τ` axis, so a node's roots stay within reach of Newton across its interval.
+struct StokesTable {
+ g: usize,
+ /// `ln(1 + τ)` at each node, ascending.
+ s: Box<[f64]>,
+ /// Row-major `[node][root]`, labeled by continuation from the roots of unity.
+ roots: Box<[Complex64]>,
+ /// Row-major `[node][root]`.
+ weights: Box<[f64]>,
+ /// Row-major `[node][dominant][recessive]`, the sign the membership step carried.
+ flips: Box<[i8]>,
+}
+
+impl StokesTable {
+ fn build(frame: &Frame) -> Self {
+ let g = frame.g;
+
+ let mut roots = vec![Complex64::default(); TABLE_NODES * g].into_boxed_slice();
+ let mut m = vec![0.0_f64; TABLE_NODES * g].into_boxed_slice();
+ let mut s = vec![0.0_f64; TABLE_NODES].into_boxed_slice();
+
+ let mut r: [Complex64; MAX_G] = [Complex64::default(); MAX_G];
+ for k in 0..g {
+ r[k] = Complex64::from_polar(1.0, TAU * k as f64 / frame.gamma);
+ }
+ let mut weights = [0.0_f64; MAX_G];
+ weights[0] = 1.0;
+ let mut sign = [0i8; MAX_G * MAX_G];
+ let mut flips = vec![0i8; TABLE_NODES * g * g].into_boxed_slice();
+
+ let phis = |r: &[Complex64; MAX_G]| -> [Complex64; MAX_G] {
+ let mut p = [Complex64::default(); MAX_G];
+ for k in 0..g {
+ p[k] = Saddle::new(r[k], frame).phi;
+ }
+ p
+ };
+
+ let mut prev_im = [0.0_f64; MAX_G * MAX_G];
+ let p = phis(&r);
+ for j in 0..g {
+ for k in 0..g {
+ prev_im[j * g + k] = (p[j] - p[k]).im;
+ }
+ }
+
+ let mut last_flip_s = 0.0_f64;
+ let mut used = 0usize;
+
+ let s_max = (1.0 + TABLE_TAU_MAX).ln();
+ for n in 0..TABLE_NODES {
+ let sn = s_max * n as f64 / (TABLE_NODES - 1) as f64;
+ let tau = sn.exp() - 1.0;
+
+ durand_kerner(&mut r, g, tau);
+ let p = phis(&r);
+
+ // A crossing is where `Im Δ` changes sign while `Re Δ > 0`, at which point the
+ // dominant saddle hands its membership across to the one it dominates.
+ let held = weights;
+ for j in 0..g {
+ for k in 0..g {
+ if j == k {
+ continue;
+ }
+ let d = p[j] - p[k];
+ let idx = j * g + k;
+ let im = d.im;
+ if d.re > 0.0 && prev_im[idx] * im < 0.0 {
+ weights[k] += im.signum() * held[j];
+ sign[idx] = im.signum() as i8;
+ last_flip_s = sn;
+ }
+ prev_im[idx] = im;
+ }
+ }
+
+ s[n] = sn;
+ roots[n * g..(n + 1) * g].copy_from_slice(&r[..g]);
+ m[n * g..(n + 1) * g].copy_from_slice(&weights[..g]);
+ flips[n * g * g..(n + 1) * g * g].copy_from_slice(&sign[..g * g]);
+ used = n + 1;
+
+ // Once the crossings have stopped coming the decomposition is settled and there is
+ // nothing left for the march to discover.
+ if sn - last_flip_s > TABLE_QUIET_SPAN && n > 8 {
+ break;
+ }
+ }
+
+ Self {
+ g,
+ s: s[..used].to_vec().into_boxed_slice(),
+ roots: roots[..used * g].to_vec().into_boxed_slice(),
+ weights: m[..used * g].to_vec().into_boxed_slice(),
+ flips,
+ }
+ }
+
+ /// The roots at `tau` with the membership they carry. Bracket into the march, take that
+ /// node's roots as a seed, and let Newton close the rest. Past the last node the
+ /// membership is settled and the roots follow their asymptotics, so the final node goes on
+ /// serving as a seed.
+ fn roots_at(&self, tau: f64, frame: &Frame) -> Membership {
+ let g = self.g;
+ let target = (1.0 + tau).ln();
+
+ let n = match self
+ .s
+ .binary_search_by(|probe| probe.partial_cmp(&target).unwrap())
+ {
+ Ok(hit) => hit,
+ Err(above) => above.min(self.s.len() - 1),
+ };
+
+ let mut r = [Complex64::default(); MAX_G];
+ r[..g].copy_from_slice(&self.roots[n * g..(n + 1) * g]);
+
+ let mut w = [0.0_f64; MAX_G];
+ w[..g].copy_from_slice(&self.weights[n * g..(n + 1) * g]);
+
+ for k in 0..g {
+ newton_trinomial(&mut r[k], g, tau);
+ }
+
+ let mut phi = [Complex64::default(); MAX_G];
+ for k in 0..g {
+ phi[k] = Saddle::new(r[k], frame).phi;
+ }
+
+ // `(1/2)erfc(-σ)`, `σ = Im Δ / √(2 Re Δ)`, less the step the march already took.
+ let mut smooth = w;
+ let mut partner = [None; MAX_G];
+ for j in 0..g {
+ if w[j].abs() <= LIVE {
+ continue;
+ }
+ for k in 0..g {
+ let s = self.flips[n * g * g + j * g + k];
+ if s == 0 {
+ continue;
+ }
+ let d = (phi[j] - phi[k]) * frame.beta;
+ if d.re <= 0.0 {
+ continue;
+ }
+ let s = s as f64;
+ let x = s * d.im / (2.0 * d.re).sqrt();
+
+ // The bracketed node already carries the whole step, so the smoothing replaces it.
+ smooth[k] += w[j] * s * (0.5 * erfc(-x) - 1.0);
+
+ if x.abs() < STOKES_REACH {
+ partner[j] = Some(k);
+ partner[k] = Some(j);
+ }
+ }
+ }
+
+ Membership {
+ roots: r,
+ weights: w,
+ smooth,
+ partner,
+ }
+ }
+
+ /// Prints the march's own record across a span of `τ`, every root and not just the live
+ /// ones, since which roots count as live is read off the very weights in question. The
+ /// integrality flag is the cheap tell. Membership is a count of steepest-descent paths and
+ /// has no business being fractional, so a row that fails it has found something the
+ /// crossing test does not understand.
+ #[cfg(test)]
+ fn dump(&self, frame: &Frame, from: f64, to: f64) {
+ println!("\n=== stokes march, tau {from:.3} to {to:.3} ===");
+ print!(" {:>6} {:>8} |", "node", "tau");
+ for k in 0..self.g {
+ print!(" {:>18}", format!("root {k}"));
+ }
+ println!(" {:>7}", "weights");
+
+ for n in 0..self.s.len() {
+ let tau = self.s[n].exp() - 1.0;
+ if tau < from || tau > to {
+ continue;
+ }
+
+ let row = &self.weights[n * self.g..(n + 1) * self.g];
+ let ragged = row.iter().any(|w| (w - w.round()).abs() > 1e-9);
+
+ print!(" {n:>6} {tau:>8.4} |");
+ for k in 0..self.g {
+ let q = self.roots[n * self.g + k];
+ let phi = Saddle::new(q, frame).phi;
+ print!(" {:>8.4}{:+8.4}i", phi.re * frame.beta, phi.im * frame.beta);
+ }
+ print!(" ");
+ for w in row {
+ let live = if w.abs() > LIVE { '*' } else { ' ' };
+ print!("{w:>5.2}{live}");
+ }
+ if ragged {
+ print!(" RAGGED");
+ }
+ println!();
+ }
+ }
+}
+
+/// Polishes a single root of `u^γ - iτu - 1` in place, quadratic from a table seed.
+fn newton_trinomial(q: &mut Complex64, g: usize, tau: f64) -> u32 {
+ let gi = g as i32;
+ let it = Complex64::i() * tau;
+ for k in 0..TABLE_NEWTON_ITERS {
+ let p = q.powi(gi) - it * *q - 1.0;
+ let dp = q.powi(gi - 1) * g as f64 - it;
+ let step = p / dp;
+ *q -= step;
+ if step.norm() < TABLE_NEWTON_TOL {
+ return k as u32 + 1;
+ }
+ }
+ TABLE_NEWTON_ITERS as u32
+}
+
+/// Solves the trinomial for all `γ` roots at once during the march, warm-started in place so
+/// that root identity survives the step.
+fn durand_kerner(r: &mut [Complex64; MAX_G], g: usize, tau: f64) {
+ for _ in 0..DK_ITERS {
+ let mut moved = 0.0_f64;
+ for k in 0..g {
+ let p = r[k].powi(g as i32) - Complex64::i() * tau * r[k] - 1.0;
+ let mut den = Complex64::new(1.0, 0.0);
+ for j in 0..g {
+ if j != k {
+ den *= r[k] - r[j];
+ }
+ }
+ let step = p / den;
+ r[k] -= step;
+ moved = moved.max(step.norm());
+ }
+ if moved < DK_TOL {
+ break;
+ }
+ }
+}
+
+/// A heavy-tailed unit kick in the plane. `t/(1 - |t|)` on a uniform `t`.
+fn kick(seed: &mut u64) -> Complex64 {
+ Complex64::new(tailed(uniform(seed)), tailed(uniform(seed)))
+}
+
+fn tailed(t: f64) -> f64 {
+ t / (1.0 - t.abs()).max(PROBE_CLIP)
+}
+
+/// xorshift64, on `(-1, 1)`.
+fn uniform(seed: &mut u64) -> f64 {
+ *seed ^= *seed << 13;
+ *seed ^= *seed >> 7;
+ *seed ^= *seed << 17;
+ 2.0 * ((*seed >> 11) as f64 / (1u64 << 53) as f64) - 1.0
+}
+
+/// The bar, as a fraction of the dominant contribution. Half of `tol` leaves the other half for
+/// the sum over saddles, and the floor is a few ulp of a partial sum that has already lost bits
+/// to cancellation.
+fn relative(tol: f64) -> f64 {
+ 0.5 * tol.max(8.0 * EPS)
+}
+
+/// How far a traced path walks, in the coordinate where the weight is exactly `e^{-x²/2}`. Far
+/// enough that the Gaussian has buried whatever the bar still cares about, and no farther, since
+/// every node past that point is spent on digits nobody reads.
+fn reach_for(bar: f64) -> f64 {
+ (2.0 * (bar + REACH_MARGIN).max(0.0)).sqrt().min(REACH_MAX)
+}
+
+/// Where the inverse map `x ↦ v` stops converging. Each neighbor puts a square-root branch
+/// point at `x_c = √(-2Δ/β)`, since that is the `x` whose target depth `-x²/2` is the neighbor's
+/// own, and the nearest of those moduli bounds the disk the series speaks for.
+fn branch_wall(seen: &[Complex64], beta: f64) -> f64 {
+ let mut wall = f64::INFINITY;
+ for &delta in seen {
+ let r = (-2.0 * delta / beta).sqrt().norm();
+ if r > GAP_FLOOR {
+ wall = wall.min(r);
+ }
+ }
+ wall
+}
+
+/// Where the subtracted polynomial stops being small at the farthest node the walk reaches.
+/// Past the wall the truncation grows like `ρ^k`, so the count is what holds that under the bar.
+/// A path that stays inside its own disk is unbounded here.
+fn wall_degree(wall: f64, beta: f64, bar: f64, rel: f64) -> usize {
+ let rho = reach_for(bar) / (beta.sqrt() * wall);
+ if rho <= 1.0 {
+ return JET_ORDER;
+ }
+ (rel.recip().ln() / rho.ln()) as usize
+}
+
+/// How far past the subtracted polynomial the coefficient tail has to run. Inside the trust
+/// radius each further order buys a factor `SERIES_TRUST`, so the count is what drives that
+/// geometric under the bar.
+fn trust_orders(rel: f64) -> usize {
+ (rel.recip().ln() / SERIES_TRUST.recip().ln()).ceil() as usize
+}
+
+/// The width the tail wants, clamped to the slots the series has. A clamp that bites is the
+/// caller's signal that the stretch has no evidence behind it.
+fn trust_width(degree: usize, rel: f64) -> usize {
+ (degree + trust_orders(rel)).min(JET_ORDER)
+}
+
+#[cfg(test)]
+mod test {
+ use num_traits::Zero;
+
+ use super::super::fmt_e;
+ use super::*;
+
+ #[test]
+ fn convergence_precision() {
+ let shape = Shape::from_q(3.5, 3.0);
+ let ref_jet = QuadJet::reference(shape);
+
+ let rel = |v: Complex64, r: Complex64| (v - r).norm() / r.norm();
+
+ // Origin, transition, the band where the jet's verdict has gone wrong before, and deep
+ // tail. Suspiciously precise probes are old sore spots.
+ let probes = [
+ 0.0, 0.8, 2.0, 2.9315, 3.7, 4.7, 5.5, 6.7, 7.911, 8.2, 8.33, 11.0, 14.0,
+ ];
+
+ #[derive(Clone, Copy)]
+ enum Channel {
+ Psi,
+ D,
+ }
+
+ let pick = |t: Channel, result: QuadJetResult| match t {
+ Channel::Psi => result.psi,
+ Channel::D => result.d,
+ };
+
+ let sweep =
+ |channel: Channel, name: &str, knob: &str, vary: &dyn Fn(u32) -> QuadJet, rows: u32| {
+ let channel_label = match channel {
+ Channel::Psi => "psi",
+ Channel::D => "d",
+ };
+ println!("\n=== {name} ({channel_label}) ===");
+ print!(" {knob:>10} |");
+ for u in probes {
+ print!(" {u:>9.2}");
+ }
+ println!();
+
+ for i in 0..rows {
+ let test_jet = vary(i);
+ let label = test_jet.tol;
+
+ print!(" {label:>10.1e} |");
+ for u in probes {
+ let v = pick(channel, test_jet.tap_at(u));
+ let r = pick(channel, ref_jet.tap_at(u));
+ print!(" {:>9}", fmt_e(rel(v, r)));
+ }
+ println!();
+ }
+ };
+
+ // Channel::D
+ for tap in [Channel::Psi, Channel::D] {
+ sweep(
+ tap,
+ "Cranking tol",
+ "tol",
+ &|i| QuadJet::new(shape, 1.0 / 10.0f64.powf((i + 1) as f64), false),
+ 18,
+ );
+ }
+
+ // Dense grid so a narrow seam can't hide between probes.
+ println!("\n=== Current Defaults ===");
+ let standard_jet = QuadJet::standard(shape);
+
+ let mut worst: f64 = 0.0;
+ let mut worst_u: f64 = 0.0;
+
+ let mut worst_time: std::time::Duration = std::time::Duration::default();
+ let mut worst_time_u: f64 = 0.0;
+
+ // NOTE this is crude and depends on settings but provides some development signal.
+ let mut matrix_time = std::time::Duration::default();
+
+ for k in 0..=2048 {
+ let u = k as f64 * 0.00625 * 0.5;
+ // for k in 0..=32 {
+ // let u = k as f64 * 0.0025 + 2.9;
+
+ let reference = ref_jet.tap_at(u);
+ let rc = reference.cost;
+ let matrix_row_start = std::time::Instant::now();
+ let standard = standard_jet.tap_at(u);
+ let elapsed = matrix_row_start.elapsed();
+ matrix_time += elapsed;
+
+ if elapsed > worst_time && k != 0 {
+ worst_time = elapsed;
+ worst_time_u = u;
+ }
+
+ let err = rel(standard.psi, reference.psi);
+ if err > worst {
+ worst = err;
+ worst_u = u;
+ }
+
+ if k % 100 == 0 {
+ // {
+ let c = standard.cost;
+ // `T` is a trace that ran out of valley, `S` is a bar the placement never met.
+ let flags = |truncated: bool, short: bool| match (truncated, short) {
+ (true, true) => "TS",
+ (true, false) => "T ",
+ (false, true) => " S",
+ (false, false) => " ",
+ };
+ println!(
+ " u: {u:>6.2}, err: {:>9}, res: {:>9}, time: {:>6}µs, jet: {:>2}s/{:>2}p/{:>3}d, quad: {:>2}p/{:>5}n+{:>5}s {}, ref: {:>2}p/{:>5}n {}, gain: {:>9}",
+ fmt_e(err),
+ fmt_e(standard.residual / standard.psi.norm()),
+ elapsed.as_micros(),
+ c.jet_saddles,
+ c.jet_passes,
+ c.jet_depth,
+ c.quad_paths,
+ c.quad_nodes,
+ c.quad_series,
+ flags(c.quad_truncated, c.quad_short),
+ rc.quad_paths,
+ rc.quad_nodes,
+ flags(rc.quad_truncated, rc.quad_short),
+ fmt_e(c.quad_gain),
+ );
+ }
+ }
+
+ println!(
+ " worst precision over grid: {} at {:0.5}",
+ fmt_e(worst),
+ worst_u
+ );
+ println!(
+ " worst time over grid: {}µs at {:0.5}",
+ worst_time.as_micros(),
+ worst_time_u
+ );
+ println!(" matrix completed in: {}µs", matrix_time.as_micros());
+ assert!(worst < 1e-4);
+ }
+
+ #[test]
+ fn stokes_membership_band() {
+ let shape = Shape::from_q(3.5, 3.0);
+ let frame = Frame::new(shape);
+ let jet = QuadJet::standard(shape);
+
+ // The band shows up in `u`, but the march lives in `τ`, and the two are related by
+ // `τ = 2πu/β` once `ω_p` cancels. Widening past the observed edges catches a flip that
+ // fires early and gets corrected late.
+ let tau_of = |u: f64| TAU * u / frame.beta;
+ jet.table.dump(&frame, tau_of(1.0), tau_of(4.0));
+ }
+}
diff --git a/mutate-lib/src/dsp/wavelet/harness/meta.rs b/mutate-lib/src/dsp/wavelet/harness/meta.rs
new file mode 100644
index 00000000..544f65e8
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/harness/meta.rs
@@ -0,0 +1,173 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # Harness Testing
+//!
+//! Avoiding the complex aspects of our harnesses, we test them against naive implementations that
+//! are prohibitively slow for regular testing but can isolate problems with the harnesses
+//! themselves.
+
+use core::f64::consts::{PI, TAU};
+
+use super::super::{
+ inspect::*,
+ spec::{Shape, WaveletSpec},
+ PEAK_GAIN,
+};
+use super::*;
+
+const RATE: f64 = 48_000.0;
+
+/// First nulls of suspicious skirts against a brute-force sign scan of Re H. Re-run this if
+/// there is ever any doubt that our null finder is missing something that dense DTFT scan would
+/// find.
+#[ignore]
+#[test]
+fn first_null_matches_dense_scan() {
+ const QUANTUM: usize = 4;
+ const TAIL_DB: f64 = -40.0;
+ /// Naive samples per bin 2π/N.
+ const PER_BIN: usize = 32;
+
+ /// (Q, γ, ρ, dir), lower skirt at −1 and upper at +1.
+ const CASES: [(f64, f64, f64, f64); 8] = [
+ (12.5, 4.0, 0.116, -1.0),
+ (12.5, 4.0, 0.116, 1.0),
+ (3.5, 3.0, 0.384, 1.0),
+ (3.5, 3.0, 0.384, -1.0),
+ (3.5, 4.0, 0.384, 1.0),
+ (3.5, 3.0, 0.189, -1.0),
+ (3.5, 3.0, 0.223, 1.0),
+ (5.0, 4.0, 0.189, -1.0),
+ ];
+
+ println!(
+ "\n=== FIRST NULL vs DENSE (quantum {QUANTUM}, tail {TAIL_DB:.0} dB) ===\n\
+ offsets in −3 dB widths from the peak, Δ in naive steps\n"
+ );
+ println!(
+ " {:>5} {:>4} {:>7} {:>5} {:>5} {:>11} {:>11} {:>10} {:>10}",
+ "Q", "𝛄", "𝛒", "side", "taps", "scanner", "naive", "Δ", "H"
+ );
+
+ let mut failures = Vec::new();
+ for (q, gamma, rho, dir) in CASES {
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(q, gamma))
+ .max_load_quantum(QUANTUM)
+ .max_truncation(TAIL_DB)
+ .bake();
+ let bin = wav.at_rho(rho);
+ let taps = bin.taps();
+ let wts = Weights::unpack(&taps);
+ let psi = wts.psi();
+
+ let r = characterize(psi, bin.velocity());
+ let lobe = r.edges.1 - r.edges.0;
+ let side = if dir < 0.0 { "lo" } else { "hi" };
+ let tag = format!("Q {q} γ {gamma} ρ {rho} {side}");
+
+ let resp = |w: f64| psi.dtft(w);
+ let from = if dir < 0.0 { r.edges.0 } else { r.edges.1 };
+ let stop = from + dir * PI;
+
+ // Naive
+ let step = TAU / (PER_BIN * psi.len_unfolded()) as f64;
+ let mut prev = (from, resp(from));
+ let naive = (1..)
+ .map(|j| from + dir * step * j as f64)
+ .take_while(|&w| dir * (stop - w) >= 0.0)
+ .find_map(|w| {
+ let q = (w, resp(w));
+ let hit = (prev.1 < 0.0) != (q.1 < 0.0);
+ let pair = (prev.0, q.0);
+ prev = q;
+ hit.then_some(pair)
+ })
+ .map(|(a, b)| bisect(&resp, a, b));
+
+ let mut buf = Vec::new();
+ let fast = Inspect::new(psi, &mut buf, OVERSAMPLE)
+ .null(from, stop)
+ .map(|(w, _)| w);
+
+ let (Some(fast), Some(naive)) = (fast, naive) else {
+ println!(
+ " {q:>5.1} {gamma:>4.1} {rho:>7.4} {side:>5} {:>5} missing",
+ psi.len_unfolded()
+ );
+ failures.push(format!("{tag} scanner {fast:?} naive {naive:?}"));
+ continue;
+ };
+
+ let off = |w: f64| (w - r.peak_w) / lobe;
+ let gap = (fast - naive).abs() / step;
+ let h_at_fast = resp(fast);
+
+ println!(
+ " {q:>5.1} {gamma:>4.1} {rho:>7.4} {side:>5} {:>5} {:>+11.6} {:>+11.6} {gap:>10.3e} \
+ {h_at_fast:>10.3e}",
+ psi.len_unfolded(),
+ off(fast),
+ off(naive),
+ );
+
+ if gap >= 1.0 {
+ failures.push(format!(
+ "{tag} scanner {:+.4} lobes, naive {:+.4} lobes",
+ off(fast),
+ off(naive)
+ ));
+ }
+ }
+
+ assert!(failures.is_empty(), "\n{}", failures.join("\n"));
+}
+
+/// The frequency domain model against the synthesized tone. Validating this lets sweeps use
+/// `pairing_residual` alone, which needs no tone and no phase loop.
+#[ignore]
+#[test]
+fn reassignment_model_agrees() {
+ const Q: f64 = 8.5;
+ const TAIL_DB: f64 = -60.0;
+ const GATE_DB: f64 = -40.0;
+ const RESOLUTION: f64 = 0.05;
+ const STEP: f64 = 100.0;
+ const SPAN: isize = 12;
+ /// The model is linear and the tone is real, so the image sets the agreement floor.
+ const TOL_C: f64 = 5e-2;
+
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(Q, 3.0))
+ .max_truncation(TAIL_DB)
+ .bake();
+
+ for (fc, sr) in [(2_000.0f64, RATE), (12_000.0, RATE)] {
+ let bin = wav.at_rho(fc / sr);
+ let taps = bin.taps();
+ let wts = Weights::unpack(&taps);
+ let (psi, d) = (wts.psi(), wts.d());
+
+ let w0 = bin.velocity();
+
+ for k in -SPAN..=SPAN {
+ let cents = k as f64 * STEP;
+ let ratio = (cents / 1200.0).exp2();
+ let h = psi.dtft(w0 * ratio).abs();
+ if 20.0 * (h / PEAK_GAIN).log10() < GATE_DB {
+ continue;
+ }
+
+ let ((bias, _), _) = tone_bias(&wts, w0, cents, RESOLUTION);
+ let (_, dr) = pairing_residual(psi, d, w0, w0 * ratio);
+ let pred = 1200.0 / LN_2 * dr / ratio;
+
+ assert!(
+ (bias - pred).abs() < TOL_C,
+ "fc {fc} detune {cents} model off {:.4}c",
+ (bias - pred).abs()
+ );
+ }
+ }
+}
diff --git a/mutate-lib/src/dsp/wavelet/harness/mod.rs b/mutate-lib/src/dsp/wavelet/harness/mod.rs
new file mode 100644
index 00000000..0a7b8f82
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/harness/mod.rs
@@ -0,0 +1,518 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # Testing Harnesses
+//!
+//! Testing harnesses and meta tests for the harnesses. We have a lot of test harness code. Some
+//! of it is complex and needs tests against less complex naive implementations that are
+//! unacceptable for general use but enable fast iteration against a naive baseline that is easier
+//! to inspect and trust.
+
+#[cfg(feature = "validate")]
+mod meta;
+
+use core::f64::consts::{PI, TAU};
+
+use num_complex::Complex64;
+
+use super::inspect::*;
+use super::{Fold, Weights};
+
+/// Max of `f` over [lo, hi] at comb density for `taps` taps.
+fn sweep(lo: f64, hi: f64, taps: usize, f: impl Fn(f64) -> f64) -> f64 {
+ let n = ((hi - lo) * OVERSAMPLE * taps as f64 / TAU).ceil().max(1.0) as usize;
+ (0..=n)
+ .map(|k| f(lo + (hi - lo) * k as f64 / n as f64))
+ .fold(0.0f64, f64::max)
+}
+
+/// max |H| on [−0.05 ω₀, 0.05 ω₀].
+pub(super) fn dc_leak(psi: Fold<'_>, w0: f64) -> f64 {
+ let e = 0.05 * w0;
+ sweep(-e, e, psi.len_unfolded(), |w| psi.dtft(w).abs())
+}
+
+/// ∫ h² dω on [lo, hi], h = max(0, 1 − dB/floor_db) with dB relative to `gain`.
+pub(super) fn level_moment(psi: Fold<'_>, gain: f64, (lo, hi): (f64, f64), floor_db: f64) -> f64 {
+ let n = ((hi - lo) * OVERSAMPLE * psi.len_unfolded() as f64 / TAU)
+ .ceil()
+ .max(1.0) as usize;
+ let dw = (hi - lo) / n as f64;
+ (0..n)
+ .map(|k| {
+ let w = lo + dw * (k as f64 + 0.5);
+ let level = db(psi.dtft(w).abs()) - db(gain);
+ (1.0 - level / floor_db).max(0.0).powi(2)
+ })
+ .sum::()
+ * dw
+}
+
+/// `|R|` and `R/Ψ` for `R = H_d(ω) − (ω/ω₀)·H_ψ(ω)`. The ratio is what lands in `r̂`, the
+/// magnitude is the floor.
+pub(super) fn pairing_residual(psi: Fold<'_>, d: Fold<'_>, w0: f64, w: f64) -> (f64, f64) {
+ let h = psi.dtft(w);
+ let r = d.dtft(w) - h * (w / w0);
+ (r.abs(), r / h)
+}
+
+/// Bias of `r̂` in cents and quadrature leak against a real tone detuned `cents` from `w0`,
+/// each as its mean over the carrier phase and its worst departure from that mean. Phases
+/// step no coarser than `min_resolution` radians across the full circle.
+pub(super) fn tone_bias(
+ wts: &Weights,
+ w0: f64,
+ cents: f64,
+ min_resolution: f64,
+) -> ((f64, f64), (f64, f64)) {
+ // ω₀ · 2^(c/1200)
+ let wd = w0 * (cents / 1200.0).exp2();
+ let n = (TAU / min_resolution).ceil().max(2.0) as usize;
+
+ let r: Vec = (0..n)
+ .map(|j| {
+ let phase = TAU * j as f64 / n as f64;
+ let tone = |k: isize| (wd * k as f64 + phase).cos();
+ let [psi, dee, _] = wts.project(tone, 0);
+ // D/Ψ
+ dee / psi
+ })
+ .collect();
+
+ let spread = |f: &dyn Fn(Complex64) -> f64| {
+ let mean = r.iter().map(|&v| f(v)).sum::() / n as f64;
+ let worst = r
+ .iter()
+ .map(|&v| (f(v) - mean).abs())
+ .fold(0.0f64, f64::max);
+ (mean, worst)
+ };
+
+ (spread(&|v| 1200.0 * v.re.log2() - cents), spread(&|v| v.im))
+}
+
+/// Departure of each lane from its phase mean, relative, after removing the carrier.
+/// Zero where the filter answers identically at every input phase. Lanes are Ψ, D, T.
+pub(super) fn tone_response(wts: &Weights, w0: f64, cents: f64, min_resolution: f64) -> [f64; 3] {
+ // ω₀ · 2^(c/1200)
+ let wd = w0 * (cents / 1200.0).exp2();
+ let n = (TAU / min_resolution).ceil().max(2.0) as usize;
+
+ // Ψ(θ) e^{−iθ}, D(θ) e^{−iθ}, T(θ) e^{−iθ}
+ let out: Vec<[Complex64; 3]> = (0..n)
+ .map(|j| {
+ let theta = TAU * j as f64 / n as f64;
+ let tone = |k: isize| (wd * k as f64 + theta).cos();
+ let carrier = Complex64::from_polar(1.0, -theta);
+ wts.project(tone, 0).map(|v| v * carrier)
+ })
+ .collect();
+
+ // |Ψ̄|, the scale every lane is read against
+ let scale = (out.iter().map(|v| v[0]).sum::() / n as f64).norm();
+
+ core::array::from_fn(|lane| {
+ let mean = out.iter().map(|v| v[lane]).sum::() / n as f64;
+ out.iter()
+ .map(|v| (v[lane] - mean).norm() / scale)
+ .fold(0.0f64, f64::max)
+ })
+}
+
+/// Signed bars for `re` and `im` overlaid on one axis, zero between cells `cols / 2 - 1` and
+/// `cols / 2`. Caller guarantees `max >= |re|` and `max >= |im|`, which keeps both spans inside
+/// the `cols` field.
+fn bar(re: f64, im: f64, max: f64, cols: usize) -> String {
+ let (cr, ci, cb) = ('●', '·', '•');
+ let half = cols / 2;
+ let span = |v: f64| {
+ let col = ((v / max) * half as f64).round() as isize;
+ let end = (half as isize + col) as usize;
+ if col >= 0 {
+ half..end
+ } else {
+ end..half
+ }
+ };
+ let (r, i) = (span(re), span(im));
+ let cells: String = (0..cols)
+ .map(|c| match (r.contains(&c), i.contains(&c)) {
+ (true, true) => cb,
+ (true, false) => cr,
+ (false, true) => ci,
+ (false, false) => ' ',
+ })
+ .collect();
+ cells.trim_end().to_string()
+}
+
+/// Edges either side of `peak_w` where the response first falls `level_db` below `peak`,
+/// searched out to `span`, absent where no crossing lies inside it.
+pub(super) fn shoulders(
+ psi: Fold<'_>,
+ peak: f64,
+ peak_w: f64,
+ level_db: f64,
+ span: f64,
+) -> (Option, Option) {
+ let mut buf = Vec::new();
+ let mut insp = Inspect::new(psi, &mut buf, OVERSAMPLE);
+ let level = db(peak) + level_db;
+ let mut edge = |stop: f64| insp.cross(level, peak_w, stop).map(|(w, _)| w);
+ (
+ edge((peak_w - span).max(0.0)),
+ edge((peak_w + span).min(PI)),
+ )
+}
+
+/// Where a bin's white noise energy lands, each a share of ∫_{−π}^{π} |H|².
+pub(super) struct Image {
+ /// ∫_guard |H(−ω)|²
+ pub beat: f64,
+ /// ∫_{¬guard} |H(−ω)|²
+ pub leak_neg: f64,
+ /// ∫_{¬guard} |H(ω)|²
+ pub leak_pos: f64,
+ /// (|H(ω)|², |H(−ω)|/|H(ω)|) inside the guard
+ pub alpha: Vec<(f64, f64)>,
+ /// (ω, |H(−ω)|) at the worst image
+ pub peak: (f64, f64),
+}
+
+/// Samples per cell for the energy shares.
+const IMAGE_OVERSAMPLE: f64 = 4.0;
+
+pub(super) fn image(psi: Fold<'_>, w0: f64) -> Image {
+ let Passband { peak_w, edges, .. } = passband(psi, w0);
+ let n = (PI * IMAGE_OVERSAMPLE * psi.len_unfolded() as f64 / TAU).ceil() as usize;
+ let dw = PI / n as f64;
+ let guard = 3.0 * (edges.1 - edges.0);
+ // 2π Σ|ψ_ν|² / dω
+ let total = TAU * psi.energy() / dw;
+
+ let (mut beat, mut leak_neg, mut leak_pos) = (0.0, 0.0, 0.0);
+ let mut alpha = Vec::new();
+ let mut peak = (0.0, 0.0f64);
+
+ for k in 0..n {
+ let w = dw * (k as f64 + 0.5);
+ let (hp, hn) = (psi.dtft(w).abs(), psi.dtft(-w).abs());
+ let (ep, en) = (hp * hp, hn * hn);
+ if (w - peak_w).abs() <= guard {
+ beat += en;
+ alpha.push((ep, hn / hp));
+ } else {
+ leak_neg += en;
+ leak_pos += ep;
+ }
+ if hn > peak.1 {
+ peak = (w, hn);
+ }
+ }
+
+ Image {
+ beat: beat / total,
+ leak_neg: leak_neg / total,
+ leak_pos: leak_pos / total,
+ alpha,
+ peak,
+ }
+}
+
+/// Gaussian-enveloped chirp, sweep rate `a` rad/sample², envelope sd in samples, centered at
+/// `p`. ω(k) = a(k − p), passing through zero at `p`.
+pub(super) fn chirp(a: f64, sd: f64, p: f64) -> impl Fn(isize) -> f64 {
+ move |k| {
+ let t = k as f64 - p;
+ let z = t / sd;
+ (-0.5 * z * z).exp() * (0.5 * a * t * t).cos()
+ }
+}
+
+/// |e| below which fraction `f` of the weight lands.
+pub(super) fn weighted_quantile(readings: &mut [(f64, f64)], f: f64) -> f64 {
+ readings.sort_by(|a, b| a.1.total_cmp(&b.1));
+ let total: f64 = readings.iter().map(|r| r.0).sum();
+ let mut acc = 0.0;
+ readings
+ .iter()
+ .find(|r| {
+ acc += r.0;
+ acc >= f * total
+ })
+ .map_or(f64::NAN, |r| r.1)
+}
+
+/// Real and imaginary parts of ψ, centered, on a shared scale.
+pub(super) fn print_wave(label: &str, psi: Fold<'_>, cols: usize) {
+ let n = psi.len_unfolded();
+ println!("\n=== {label} ===");
+ let max = psi
+ .mirrored()
+ .map(|h| h.re.abs().max(h.im.abs()))
+ .fold(0.0f64, f64::max);
+
+ for (j, h) in psi.mirrored().enumerate() {
+ println!(
+ "{:>6} {:>12.7} {:>12.7} {}",
+ j as isize - (n / 2) as isize,
+ h.re,
+ h.im,
+ bar(h.re, h.im, max, cols)
+ );
+ }
+}
+
+/// Shading ramp, floor to peak.
+const SHADE: [char; 5] = [' ', '░', '▒', '▓', '█'];
+
+/// |W(t, ω₀)| over hops and bins, `floor_db` below the loudest cell. Rows are `(ω₀, table)`
+/// in print order, columns are hops [−span, span].
+pub(super) fn print_transform(
+ label: &str,
+ bank: &[(f64, Weights)],
+ x: impl Fn(isize) -> f64,
+ span: isize,
+ cols: usize,
+ floor_db: f64,
+) {
+ let step = 2.0 * span as f64 / (cols - 1) as f64;
+ let at = |c: usize| -(span as f64) + step * c as f64;
+ let aa = step.ceil() as usize;
+
+ // (1/aa) Σ |Ψ(m)| over the hops a column covers
+ let mag: Vec> = bank
+ .iter()
+ .map(|(_, wts)| {
+ (0..cols)
+ .map(|c| {
+ (0..aa)
+ .map(|j| {
+ let u = at(c) + step * ((j as f64 + 0.5) / aa as f64 - 0.5);
+ wts.project(&x, u.round() as isize)[0].norm()
+ })
+ .sum::()
+ / aa as f64
+ })
+ .collect()
+ })
+ .collect();
+
+ let peak = mag.iter().flatten().fold(0.0f64, |m, &v| m.max(v));
+
+ println!("\n=== {label} ===");
+ println!(" {floor_db:.0} dB to peak over {} hops", 2 * span);
+
+ for (&(w0, _), row) in bank.iter().zip(&mag) {
+ let cells: String = row
+ .iter()
+ .map(|&v| {
+ let db = 20.0 * (v / peak).log10();
+ let q = (1.0 - db / floor_db).clamp(0.0, 1.0);
+ SHADE[(q * (SHADE.len() - 1) as f64).round() as usize]
+ })
+ .collect();
+ println!("{w0:>9.6} {:>9.5} |{cells}|", w0 / TAU);
+ }
+}
+
+// NOTE Some testing "helpers" in their infancy. The goal is to start working on the matrix macros
+// so that our scans are more regular and then to crank up the code compression to make the test
+// behavior easy to read and compare at a glance. The newer style of tests is being supported first
+// class in order to keep going in that direction.
+
+/// A continuous test axis, sampled by `survey` and integrated over.
+#[derive(Clone, Copy)]
+pub(crate) enum Span {
+ Lin(f64, f64),
+ Log(f64, f64),
+}
+
+impl Span {
+ fn at(self, u: f64) -> f64 {
+ match self {
+ Span::Lin(a, b) => a + (b - a) * u,
+ // a (b/a)^u
+ Span::Log(a, b) => a * (b / a).powf(u),
+ }
+ }
+
+ /// The span's value at `u = 1`.
+ pub fn end(self) -> f64 {
+ self.at(1.0)
+ }
+}
+
+/// A discrete test axis, enumerated as weighted levels.
+#[derive(Clone, Copy)]
+pub(crate) enum Axis {
+ /// Equal weights
+ Levels(&'static [f64]),
+ /// Explicit levels, log cells
+ LogLevels(&'static [f64]),
+ /// a + k·step toward b, linear cells
+ Step(f64, f64, f64),
+ /// a·2^(k/n) up to b, log cells
+ PerOctave(f64, f64, usize),
+}
+
+impl Axis {
+ /// (w, x) in order, Σ w = 1
+ pub fn levels(self) -> Vec<(f64, f64)> {
+ match self {
+ Axis::Levels(l) => l.iter().map(|&x| (1.0 / l.len() as f64, x)).collect(),
+ Axis::LogLevels(l) => weigh(l.to_vec(), f64::ln),
+ Axis::Step(a, b, step) => {
+ let n = ((b - a).abs() / step + 1e-9) as usize;
+ let s = step.copysign(b - a);
+ weigh((0..=n).map(|k| a + k as f64 * s).collect(), |x| x)
+ }
+ Axis::PerOctave(a, b, n) => {
+ let m = (n as f64 * (b / a).log2() + 1e-9) as usize;
+ weigh(
+ (0..=m).map(|k| a * (k as f64 / n as f64).exp2()).collect(),
+ f64::ln,
+ )
+ }
+ }
+ }
+}
+
+/// Levels weighted by their cells in coordinate `t`, split at midpoints and clipped to the ends.
+fn weigh(x: Vec, t: impl Fn(f64) -> f64) -> Vec<(f64, f64)> {
+ let t: Vec = x.iter().map(|&x| t(x)).collect();
+ let last = t.len() - 1;
+ if last == 0 {
+ return vec![(1.0, x[0])];
+ }
+ let span = (t[last] - t[0]).abs();
+ (0..=last)
+ .map(|i| {
+ let lo = if i == 0 {
+ t[0]
+ } else {
+ 0.5 * (t[i - 1] + t[i])
+ };
+ let hi = if i == last {
+ t[last]
+ } else {
+ 0.5 * (t[i] + t[i + 1])
+ };
+ ((hi - lo).abs() / span, x[i])
+ })
+ .collect()
+}
+
+/// Points crowded toward the faces, weighted so weighted means estimate the uniform measure.
+///
+/// u = ½(1 − cos πs), w = Π ½π sin(πs)
+pub(crate) fn survey(
+ axes: [Span; D],
+ n: usize,
+) -> impl Iterator
- {
+ // φ_d^{d+1} = φ_d + 1
+ let phi = (0..32).fold(2.0f64, |x, _| (1.0 + x).powf(1.0 / (D as f64 + 1.0)));
+ // α_j = φ_d^{−(j+1)}
+ let alpha: [f64; D] = core::array::from_fn(|j| phi.powi(-(j as i32 + 1)));
+
+ (0..n).map(move |i| {
+ // {(i + ½) α}
+ let s: [f64; D] = alpha.map(|a| ((i as f64 + 0.5) * a).fract());
+ let w = s.iter().map(|s| 0.5 * PI * (PI * s).sin()).product();
+ let x = core::array::from_fn(|j| axes[j].at(0.5 * (1.0 - (PI * s[j]).cos())));
+ (w, x)
+ })
+}
+
+/// Weighted readings of err / tol.
+#[derive(Default)]
+pub(super) struct Ledger {
+ rows: Vec<(f64, f64, Vec<(&'static str, f64)>)>,
+}
+
+impl Ledger {
+ pub(super) fn record(&mut self, w: f64, r: f64, at: Vec<(&'static str, f64)>) {
+ self.rows.push((w, r, at));
+ }
+
+ /// Σ w [r < 1] / Σ w
+ pub fn good(&self) -> f64 {
+ self.mean(|r| if r < 1.0 { 1.0 } else { 0.0 })
+ }
+
+ /// Σ w min(max(r − 1, 0), 1) / Σ w
+ pub fn excess(&self) -> f64 {
+ self.mean(|r| match r {
+ r if r < 1.0 => 0.0,
+ r if r < 2.0 => r - 1.0,
+ _ => 1.0,
+ })
+ }
+
+ fn mean(&self, f: impl Fn(f64) -> f64) -> f64 {
+ let (num, den) = self
+ .rows
+ .iter()
+ .fold((0.0, 0.0), |(n, d), (w, r, _)| (n + w * f(*r), d + w));
+ num / den
+ }
+
+ pub fn absorb(&mut self, other: Ledger) {
+ self.rows.extend(other.rows);
+ }
+
+ /// The `k` largest err / tol, one column per coordinate.
+ pub(super) fn print_worst(&mut self, k: usize) {
+ self.rows.sort_by(|a, b| b.1.total_cmp(&a.1));
+
+ print!("\n {:>9} {:>9}", "err/tol", "weight");
+ for (name, _) in &self.rows[0].2 {
+ print!(" {name:>9}");
+ }
+ println!();
+
+ for (w, r, at) in self.rows.iter().take(k) {
+ print!(" {r:>9.4} {w:>9.2e}");
+ for (_, v) in at {
+ print!(" {v:>9.4}");
+ }
+ println!();
+ }
+ }
+
+ /// Pooled masses against a good floor and an excess ceiling, returned as `[good, excess]`.
+ pub(super) fn verdict(&self, limits: [f64; 2]) -> [f64; 2] {
+ let measured = [self.good(), self.excess()];
+ let headroom = [measured[0] - limits[0], limits[1] - measured[1]];
+ let verdict = |h: f64| if h > 0.0 { "pass" } else { "FAIL" };
+ let rule = "=".repeat(33);
+
+ println!("\n {rule}");
+ println!(" {:>9} {:>11} {:>11}", "mass", "good", "excess");
+ println!(" {rule}");
+ for (label, [g, e]) in [
+ ("measured", measured),
+ ("limit", limits),
+ ("headroom", headroom),
+ ] {
+ println!(" {label:>9} {g:>11.4} {e:>11.2e}");
+ }
+ println!(
+ " {:>9} {:>11} {:>11}",
+ "",
+ verdict(headroom[0]),
+ verdict(headroom[1])
+ );
+ println!(" {rule}");
+
+ measured
+ }
+}
+
+/// Named coordinates of a reading.
+macro_rules! at {
+ ($($v:ident),+ $(,)?) => {
+ vec![$((stringify!($v), $v as f64)),+]
+ };
+}
+pub(super) use at;
diff --git a/mutate-lib/src/dsp/wavelet/inspect.rs b/mutate-lib/src/dsp/wavelet/inspect.rs
new file mode 100644
index 00000000..61b60921
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/inspect.rs
@@ -0,0 +1,712 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # Inspect
+//!
+//! Analytic filter generation can only work up to what we can analytically predict. Beyond what we
+//! can predict in a vacuum, anything further must be grounded in the empirical reality of what we
+//! have built.
+//!
+//! > We stand on the grave of the monarchy as evidence that when the many unite to tear down the
+//! > powers that be, what comes to pass can only be a superior form of government.
+//! >
+//! > - Oliver Cromwell, Lord Protector of the Commonwealth of New England
+//!
+//! - [`Inspect::peak`] finds a local maximum, usually a peak.
+//! - [`Inspect::cross`] finds where the response meets a level.
+//! - [`Inspect::skirt`] finds where the main lobe ends and every lobe past it.
+//! - [`Inspect::tallest`] pins the highest of a set of crests.
+
+// NOTE see the harness module. Natural two-way flow of code between tests and filter inspections
+// used to tune filters.
+// DEBT may be committed in the middle of duplicating some code over. Re-enable warnings and try
+// not to cry about it.
+
+use core::f64::consts::{PI, TAU};
+
+use super::Fold;
+
+/// ω and the response there.
+pub(super) type Sample = (f64, f64);
+
+/// Outer samples of a window that brackets a feature, in walking order.
+type Bracket = (Sample, Sample);
+
+/// Transforms one stencil costs, the unit every decision is priced in.
+const STENCIL: f64 = 3.0;
+
+/// Which scalar the stencils model.
+#[derive(Clone, Copy)]
+enum Level {
+ /// |H|, cusped at every null
+ Mag,
+ /// |H| − target
+ Offset(f64),
+}
+
+/// Which feature of that scalar the walk hunts.
+#[derive(Clone, Copy)]
+enum Seek {
+ Crest,
+ Trough,
+ Zero,
+}
+
+impl Seek {
+ /// Sign turning the feature into a crest.
+ fn up(&self) -> f64 {
+ match self {
+ Seek::Trough => -1.0,
+ _ => 1.0,
+ }
+ }
+
+ /// Whether the middle of three samples is the feature.
+ fn marks(&self, w: &[Sample]) -> bool {
+ let e = self.up();
+ e * w[0].1 <= e * w[1].1 && e * w[1].1 > e * w[2].1
+ }
+
+ /// Model locations of the feature, non-finite where absent.
+ fn locate(&self, l: &Local) -> [f64; 2] {
+ match self {
+ // w − s/k on the side curving toward the feature
+ Seek::Crest | Seek::Trough => match self.up() * l.k < 0.0 {
+ true => [l.vertex(), f64::NAN],
+ false => [f64::NAN; 2],
+ },
+ Seek::Zero => l.roots().map(|t| l.w + t),
+ }
+ }
+
+ fn witness(&self, p: &[Sample]) -> Option {
+ match self {
+ Seek::Crest | Seek::Trough => {
+ p.windows(3).find(|w| self.marks(w)).map(|w| (w[0], w[2]))
+ }
+ Seek::Zero => p
+ .windows(2)
+ .find(|w| (w[0].1 < 0.0) != (w[1].1 < 0.0))
+ .map(|w| (w[0], w[1])),
+ }
+ }
+
+ /// Whether a landing is evidence the walk has left a crest behind: below where it started,
+ /// convex, and rising back the way it came.
+ fn retreat(&self, start: &Local, new: &Local, dir: f64) -> bool {
+ match self {
+ Seek::Crest => new.g[1] < start.g[1] && new.k > 0.0 && dir * new.s < 0.0,
+ _ => false,
+ }
+ }
+}
+
+/// Quadratic model of a response on [w − step, w + step].
+#[derive(Clone, Copy)]
+struct Local {
+ w: f64,
+ step: f64,
+ g: [f64; 3],
+ s: f64,
+ k: f64,
+}
+
+impl Local {
+ fn new(w: f64, step: f64, g: [f64; 3]) -> Self {
+ Local {
+ w,
+ step,
+ g,
+ // (g₊ − g₋) / 2h
+ s: (g[2] - g[0]) / (2.0 * step),
+ // (g₊ − 2g₀ + g₋) / h²
+ k: (g[2] - 2.0 * g[1] + g[0]) / (step * step),
+ }
+ }
+
+ fn points(&self) -> [Sample; 3] {
+ [
+ (self.w - self.step, self.g[0]),
+ (self.w, self.g[1]),
+ (self.w + self.step, self.g[2]),
+ ]
+ }
+
+ /// w − s/k
+ fn vertex(&self) -> f64 {
+ self.w - self.s / self.k
+ }
+
+ /// τ solving g₀ + sτ + ½kτ² = 0, paired to keep each root off its cancelling branch.
+ fn roots(&self) -> [f64; 2] {
+ // √(s² − 2k g₀)
+ let disc = (self.s * self.s - 2.0 * self.k * self.g[1]).sqrt();
+ let q = -0.5 * (self.s + disc.copysign(self.s));
+ [2.0 * q / self.k, self.g[1] / q]
+ }
+}
+
+/// Candidate nearest `w` among `cands`, on the `side` given, outside the stencil's span.
+fn aim_at(cands: [f64; 2], l: &Local, side: impl Fn(f64) -> bool) -> Option {
+ cands
+ .into_iter()
+ .filter(|v| v.is_finite() && side(*v) && (v - l.w).abs() > 2.0 * l.step)
+ .min_by(|a, b| (a - l.w).abs().total_cmp(&(b - l.w).abs()))
+}
+
+/// A local maximum as the comb sees it, carrying the bracket that pins it.
+#[derive(Clone, Copy)]
+pub(super) struct Crest {
+ /// ω and |H| at the comb sample
+ pub at: Sample,
+ bracket: Bracket,
+}
+
+/// Taps, scratch, and the resolution every hunt over them shares.
+pub(super) struct Inspect<'a> {
+ psi: Fold<'a>,
+ buf: &'a mut Vec,
+ comb: Comb,
+ /// transforms spent since the current walk began
+ spent: f64,
+}
+
+impl<'a> Inspect<'a> {
+ /// ψ over [0, K), combed at `over` samples per cell.
+ pub(super) fn new(psi: Fold<'a>, buf: &'a mut Vec, over: f64) -> Self {
+ Inspect {
+ comb: Comb::new(psi, over),
+ psi,
+ buf,
+ spent: 0.0,
+ }
+ }
+
+ /// ω and |H| at the highest point in the basin around `from`, within [lo, hi]. The start
+ /// stencil only picks which side to try first.
+ pub(super) fn peak(&mut self, from: f64, lo: f64, hi: f64) -> Option {
+ let start = self.local(Level::Mag, from);
+ let (ahead, behind) = match start.s > 0.0 {
+ true => (hi, lo),
+ false => (lo, hi),
+ };
+ self.hunt(Level::Mag, Seek::Crest, start, ahead)
+ .or_else(|| self.hunt(Level::Mag, Seek::Crest, start, behind))
+ }
+
+ /// ω and |H| where the response first meets `level` dB, from `from` toward `stop`.
+ pub(super) fn cross(&mut self, level: f64, from: f64, stop: f64) -> Option {
+ let what = Level::Offset(10f64.powf(level / 20.0));
+ let start = self.local(what, from);
+ self.hunt(what, Seek::Zero, start, stop)
+ .map(|(w, _)| self.eval(Level::Mag, w))
+ }
+
+ fn eval(&mut self, what: Level, w: f64) -> Sample {
+ self.spent += 1.0;
+ let h = self.psi.dtft(w).abs();
+ let y = match what {
+ Level::Mag => h,
+ Level::Offset(t) => h - t,
+ };
+ (w, y)
+ }
+
+ fn local(&mut self, what: Level, w: f64) -> Local {
+ let step = self.comb.step;
+ let g = [
+ self.eval(what, w - step).1,
+ self.eval(what, w).1,
+ self.eval(what, w + step).1,
+ ];
+ Local::new(w, step, g)
+ }
+
+ /// `p` sorted along +dir, in scratch.
+ fn sorted(&mut self, p: impl IntoIterator
- , dir: f64) {
+ self.buf.clear();
+ self.buf.extend(p);
+ self.buf.sort_by(|a, b| (dir * a.0).total_cmp(&(dir * b.0)));
+ }
+
+ /// Feature inside a bracket.
+ fn pin(&mut self, what: Level, seek: Seek, t: Bracket) -> Sample {
+ let (mut a, mut b) = (t.0 .0, t.1 .0);
+ match seek {
+ Seek::Crest | Seek::Trough => {
+ let e = seek.up();
+ (a, b) = (a.min(b), a.max(b));
+ // 2/3 per step from one cell to f64 resolution of ω
+ for _ in 0..96 {
+ let (m1, m2) = (a + (b - a) / 3.0, b - (b - a) / 3.0);
+ if m1 >= m2 {
+ break;
+ }
+ match e * self.eval(what, m1).1 < e * self.eval(what, m2).1 {
+ true => a = m1,
+ false => b = m2,
+ }
+ }
+ self.eval(what, 0.5 * (a + b))
+ }
+ Seek::Zero => {
+ let neg = t.0 .1 < 0.0;
+ loop {
+ let m = 0.5 * (a + b);
+ if m == a || m == b {
+ return self.eval(what, m);
+ }
+ let y = self.eval(what, m).1;
+ if y == 0.0 {
+ return (m, y);
+ }
+ match (y < 0.0) == neg {
+ true => a = m,
+ false => b = m,
+ }
+ }
+ }
+ }
+ }
+
+ /// Bracket refined by aiming stencils where the model puts the feature, until a step stops
+ /// saving more transforms than it costs.
+ fn tighten(&mut self, what: Level, seek: Seek, mut t: Bracket, mut aim: Local) -> Bracket {
+ loop {
+ let dir = (t.1 .0 - t.0 .0).signum();
+ let width = (t.1 .0 - t.0 .0).abs() * self.comb.density;
+ let (lo, hi) = (t.0 .0.min(t.1 .0) + aim.step, t.0 .0.max(t.1 .0) - aim.step);
+
+ if width <= STENCIL {
+ return t;
+ }
+ let Some(v) = aim_at(seek.locate(&aim), &aim, |v| v > lo && v < hi) else {
+ return t;
+ };
+
+ let next = self.local(what, v);
+ self.sorted([t.0, t.1].into_iter().chain(next.points()), dir);
+ let Some(u) = seek.witness(self.buf) else {
+ return t;
+ };
+ if (u.1 .0 - u.0 .0).abs() * self.comb.density > width - STENCIL {
+ return u;
+ }
+ (t, aim) = (u, next);
+ }
+ }
+
+ /// Walk toward `stop`, aiming stencils by the model, combing any span the model cannot
+ /// clear and any remainder the walk stops being cheaper than.
+ fn hunt(&mut self, what: Level, seek: Seek, start: Local, stop: f64) -> Option {
+ let dir = (stop - start.w).signum();
+ let clamp = |w: f64| match dir * (w - stop) > 0.0 {
+ true => stop,
+ false => w,
+ };
+ let ahead = |v: f64, from: f64| dir * (v - from) > 0.0;
+
+ self.spent = 0.0;
+ self.sorted(start.points(), dir);
+ if let Some(t) = seek.witness(self.buf) {
+ let t = self.tighten(what, seek, t, start);
+ return Some(self.pin(what, seek, t));
+ }
+
+ let mut old = start;
+ let mut jump = 2.0 * self.comb.step;
+ let mut blind = 0u32;
+ loop {
+ let seen = aim_at(seek.locate(&old), &old, |v| ahead(v, old.w));
+ blind = match seen {
+ Some(_) => 0,
+ None => blind + 1,
+ };
+ // no model twice running leaves the remainder unevidenced
+ if blind > 1 {
+ let t = self.comb(what, seek, old.w, stop)?;
+ return Some(self.pin(what, seek, t));
+ }
+
+ jump = seen
+ .map_or(2.0 * jump, |v| (v - old.w).abs())
+ .min(self.comb.cap);
+ let land = clamp(old.w + dir * jump);
+ let new = self.local(what, land);
+
+ self.sorted(old.points().into_iter().chain(new.points()), dir);
+ if let Some(t) = seek.witness(self.buf) {
+ let aim = match seek.locate(&new)[0].is_finite() {
+ true => new,
+ false => old,
+ };
+ let t = self.tighten(what, seek, t, aim);
+ return Some(self.pin(what, seek, t));
+ }
+
+ // model puts an extremum inside the span
+ let (lo, hi) = (old.w.min(land), old.w.max(land));
+ if new.k.is_finite() && new.vertex() > lo && new.vertex() < hi {
+ if let Some(t) = self.comb(what, seek, old.w, land) {
+ return Some(self.pin(what, seek, t));
+ }
+ }
+
+ if seek.retreat(&start, &new, dir) {
+ return None;
+ }
+
+ if land == stop {
+ let t = self.comb(what, seek, old.w, stop)?;
+ return Some(self.pin(what, seek, t));
+ }
+ if self.spent + STENCIL >= (stop - land).abs() * self.comb.density {
+ let t = self.comb(what, seek, land, stop)?;
+ return Some(self.pin(what, seek, t));
+ }
+ old = new;
+ }
+ }
+
+ /// `what` over [a, b] at comb density, in scratch.
+ fn sweep(&mut self, what: Level, a: f64, b: f64) {
+ let n = ((b - a).abs() * self.comb.density).ceil().max(2.0) as usize;
+ self.buf.clear();
+ for j in 0..=n {
+ let w = a + (b - a) * j as f64 / n as f64;
+ let s = self.eval(what, w);
+ self.buf.push(s);
+ }
+ }
+
+ /// Bracket from a uniform sweep of [a, b].
+ fn comb(&mut self, what: Level, seek: Seek, a: f64, b: f64) -> Option {
+ self.sweep(what, a, b);
+ seek.witness(self.buf)
+ }
+
+ /// Every local maximum of |H| between `from` and `stop`, at comb density, in walking order.
+ pub(super) fn crests(&mut self, from: f64, stop: f64) -> Vec {
+ self.sweep(Level::Mag, from, stop);
+ crests_in(self.buf)
+ }
+
+ /// First dip of |H| from `from` toward `stop` whose next crest clears it by `rise_db`, and
+ /// every crest past it in walking order. Shallower dips are shoulders of the main lobe.
+ pub(super) fn skirt(
+ &mut self,
+ from: f64,
+ stop: f64,
+ rise_db: f64,
+ ) -> Option<(Sample, Vec)> {
+ let rise = 10f64.powf(rise_db / 20.0);
+ self.sweep(Level::Mag, from, stop);
+ let mut at = 0;
+ // middle index of the admitted trough
+ let d = loop {
+ let d = at
+ + 1
+ + self.buf[at..]
+ .windows(3)
+ .position(|w| Seek::Trough.marks(w))?;
+ let Some(c) = self.buf[d..].windows(3).position(|w| Seek::Crest.marks(w)) else {
+ break d;
+ };
+ let c = d + 1 + c;
+ if self.buf[c].1 >= rise * self.buf[d].1 {
+ break d;
+ }
+ at = c;
+ };
+ let dip = (self.buf[d - 1], self.buf[d + 1]);
+ let lobes = crests_in(&self.buf[d..]);
+ Some((self.pin(Level::Mag, Seek::Trough, dip), lobes))
+ }
+
+ /// Highest of `found`, pinning the `PIN` tallest by comb height.
+ pub(super) fn tallest(&mut self, mut found: Vec) -> Option {
+ found.sort_by(|a, b| b.at.1.total_cmp(&a.at.1));
+ found
+ .into_iter()
+ .take(PIN)
+ .map(|c| self.pin(Level::Mag, Seek::Crest, c.bracket))
+ .max_by(|a, b| a.1.total_cmp(&b.1))
+ }
+}
+
+/// Crests pinned before the tallest is chosen, enough to cover near ties at comb resolution.
+const PIN: usize = 4;
+
+/// Every crest in `p`, bracketed by its comb neighbors.
+fn crests_in(p: &[Sample]) -> Vec {
+ p.windows(3)
+ .filter(|w| Seek::Crest.marks(w))
+ .map(|w| Crest {
+ at: w[1],
+ bracket: (w[0], w[2]),
+ })
+ .collect()
+}
+
+/// Comb samples per null spacing. Four resolves every extremum a degree K polynomial admits.
+pub(super) const OVERSAMPLE: f64 = 16.0;
+
+/// Sampling limits for H, a trigonometric polynomial of degree K = (N−1)/2. Its 2K roots per
+/// turn bound how close two features can sit, so a comb at `over` samples per cell resolves
+/// every one.
+#[derive(Clone, Copy)]
+pub(super) struct Comb {
+ /// stencil half width
+ step: f64,
+ /// comb samples per radian
+ density: f64,
+ /// longest jump the straddle test is trusted across
+ cap: f64,
+}
+
+impl Comb {
+ /// `over` samples per cell.
+ pub(super) fn new(psi: Fold<'_>, over: f64) -> Self {
+ // 2π/N, the narrowest feature H can carry
+ let cell = TAU / psi.len_unfolded() as f64;
+ Comb {
+ step: cell / over,
+ density: over / cell,
+ cap: cell,
+ }
+ }
+}
+
+/// -∞ representable, so a null is a number.
+pub(super) fn db(mag: f64) -> f64 {
+ 20.0 * mag.max(f64::MIN_POSITIVE).log10()
+}
+
+/// Crest of the main lobe and its half-power edges.
+#[derive(Clone, Copy)]
+pub(super) struct Passband {
+ pub peak_w: f64,
+ /// |H(peak_w)|
+ pub gain: f64,
+ pub edges: (f64, f64),
+}
+
+/// Peak and -3 dB edges. `w0` seeds the climb and brackets the edges.
+pub(super) fn passband(psi: Fold<'_>, w0: f64) -> Passband {
+ let mut buf = Vec::new();
+ let mut insp = Inspect::new(psi, &mut buf, OVERSAMPLE);
+
+ let (peak_w, gain) = insp.peak(w0, 0.0, PI).expect("no crest in [0, π]");
+
+ // |H(peak)| / √2
+ let half_power = db(gain) - 10.0 * 2.0f64.log10();
+ let (lo_stop, hi_stop) = ((peak_w - w0).max(0.0), (peak_w + w0).min(PI));
+ let lo = insp.cross(half_power, peak_w, lo_stop);
+ let hi = insp.cross(half_power, peak_w, hi_stop);
+
+ Passband {
+ peak_w,
+ gain,
+ edges: (
+ lo.map_or(lo_stop, |(w, _)| w),
+ hi.map_or(hi_stop, |(w, _)| w),
+ ),
+ }
+}
+
+/// Cells either side of the antipode a floor scan covers, enough to hold a crest.
+const FLOOR_CELLS: f64 = 1.5;
+/// Widest floor scan, π/8, where the symmetric envelope rises well under a dB.
+const FLOOR_REACH_CAP: f64 = PI / 8.0;
+
+/// Maximum roll-off. Highest |H| within min(1.5 cells, π/8) of the antipode ω_peak − π. The
+/// returned value may i
+fn floor(psi: Fold<'_>, insp: &mut Inspect<'_>, peak_w: f64) -> f64 {
+ // ω_peak − π
+ let at = peak_w - PI;
+ // min(c · 2π/N, π/8)
+ let reach = (FLOOR_CELLS * TAU / psi.len_unfolded() as f64).min(FLOOR_REACH_CAP);
+ let edges = psi.dtft(at - reach).abs().max(psi.dtft(at + reach).abs());
+ let found = insp.crests(at - reach, at + reach);
+ insp.tallest(found).map_or(edges, |t| t.1.max(edges))
+}
+
+pub(super) struct Response {
+ pub peak_w: f64,
+ /// |H(peak_w)|
+ pub gain: f64,
+ pub edges: (f64, f64),
+ pub rel_width: f64,
+ /// max |H| on [−π, 0]
+ pub image: f64,
+ pub floor: f64,
+}
+
+/// One side of the response past the main lobe.
+#[derive(Default)]
+pub(super) struct Skirt {
+ /// First dip past the edge, where the main lobe ends.
+ pub dip: Option,
+ /// Tallest lobe past the dip.
+ pub peak: Option,
+ /// Lobes past the dip.
+ pub lobes: usize,
+}
+
+/// Rise a lobe must clear its dip by to end the main lobe, dB. Shallower dips are shoulders.
+const SHOULDER_DB: f64 = 1.0;
+
+/// Dip from `edge` toward `stop` and the lobes past it.
+fn skirt(psi: Fold<'_>, edge: f64, stop: f64) -> Skirt {
+ let mut buf = Vec::new();
+ let mut insp = Inspect::new(psi, &mut buf, OVERSAMPLE);
+ let Some((dip, lobes)) = insp.skirt(edge, stop, SHOULDER_DB) else {
+ return Skirt::default();
+ };
+ Skirt {
+ dip: Some(dip),
+ lobes: lobes.len(),
+ peak: insp.tallest(lobes),
+ }
+}
+
+/// Both skirts outward from the half-power edges past the antipode ω_peak ± π, overlapping by a
+/// cell so a lobe straddling the antipode is a crest to both.
+pub(super) fn skirts(psi: Fold<'_>, r: &Response) -> (Skirt, Skirt) {
+ // π + 2π/N
+ let reach = PI + TAU / psi.len_unfolded() as f64;
+ (
+ skirt(psi, r.edges.0, r.peak_w - reach),
+ skirt(psi, r.edges.1, r.peak_w + reach),
+ )
+}
+
+/// Root of `resp` in a sign-changing bracket.
+pub(super) fn bisect(resp: impl Fn(f64) -> f64, mut a: f64, mut b: f64) -> f64 {
+ let fa = resp(a) < 0.0;
+ for _ in 0..64 {
+ let m = 0.5 * (a + b);
+ if m == a || m == b {
+ break;
+ }
+ let fm = resp(m);
+ if fm == 0.0 {
+ return m;
+ }
+ if (fm < 0.0) == fa {
+ a = m;
+ } else {
+ b = m;
+ }
+ }
+ 0.5 * (a + b)
+}
+
+/// Transition transport from each −3 dB edge out to its PSL crest, dB re one lobe width.
+///
+/// E·d = ∫_transition |H|² d dω / (W ∫_lobe |H|² dω)
+///
+/// d is the distance from the edge and W the lobe width. Both sides share the lobe term, so
+/// they sum linearly to the two sided transport.
+pub(super) fn transition_mass(
+ psi: Fold<'_>,
+ (e_lo, e_hi): (f64, f64),
+ below: &Skirt,
+ above: &Skirt,
+) -> (Option, Option) {
+ let width = e_hi - e_lo;
+ let taps = psi.len_unfolded() as f64;
+
+ // ∫_a^b |H|² f(ω) dω
+ let integrate = |a: f64, b: f64, f: &dyn Fn(f64) -> f64| {
+ let n = ((b - a) * OVERSAMPLE * taps / TAU).ceil().max(1.0) as usize;
+ let dw = (b - a) / n as f64;
+ (0..n)
+ .map(|k| {
+ let w = a + dw * (k as f64 + 0.5);
+ psi.dtft(w).powi(2) * f(w)
+ })
+ .sum::()
+ * dw
+ };
+
+ // W ∫_lobe |H|²
+ let right = width * integrate(e_lo, e_hi, &|_| 1.0);
+ let to_db = |wrong: f64| 10.0 * (wrong / right).log10();
+
+ (
+ below
+ .peak
+ .map(|(p, _)| to_db(integrate(p, e_lo, &|w| e_lo - w))),
+ above
+ .peak
+ .map(|(p, _)| to_db(integrate(e_hi, p, &|w| w - e_hi))),
+ )
+}
+
+/// Passband, -3 dB relative width, image, and the stopband floor.
+pub(super) fn characterize(psi: Fold<'_>, w0: f64) -> Response {
+ let Passband {
+ peak_w,
+ gain,
+ edges: (lo, hi),
+ } = passband(psi, w0);
+
+ let mut buf = Vec::new();
+ let mut insp = Inspect::new(psi, &mut buf, OVERSAMPLE);
+
+ // |H(−π)|, the fold
+ let fold = (-PI, psi.dtft(-PI).abs());
+
+ // max |H| on [−π, 0]
+ let found = insp.crests(0.0, -PI);
+ let (image_w, image) = insp.tallest(found).filter(|t| t.1 > fold.1).unwrap_or(fold);
+
+ let floor = floor(psi, &mut insp, peak_w);
+
+ Response {
+ peak_w,
+ gain,
+ edges: (lo, hi),
+ rel_width: (hi - lo) / peak_w,
+ image,
+ floor,
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use core::f64::consts::PI;
+
+ use super::super::{Shape, WaveletSpec, Weights, PEAK_GAIN};
+ use super::*;
+
+ #[test]
+ fn peak_gain_is_found() {
+ // Make a wavelet slightly outside of the normal path. Find the peak location and gain at
+ // the peak.
+
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(3.5, 3.0))
+ .max_truncation(-120.0)
+ .bake();
+
+ let bin = wav.bin(2_000.0, 48_000.0);
+ let wts = bin.weights();
+
+ let w0 = bin.velocity();
+ let mut buf = Vec::new();
+
+ let (w, gain) = Inspect::new(wts.psi(), &mut buf, OVERSAMPLE)
+ .peak(w0, 0.0, PI)
+ .expect("no crest in [0, pi]");
+
+ println!(
+ "w0 {w0:.9} peak {w:.9} {:+.3} cents",
+ 1200.0 * (w / w0).log2()
+ );
+ println!("gain {:.9}", gain);
+
+ assert!((gain / PEAK_GAIN - 1.0).abs() < 1e-3);
+ }
+}
diff --git a/mutate-lib/src/dsp/wavelet/mod.rs b/mutate-lib/src/dsp/wavelet/mod.rs
new file mode 100644
index 00000000..65152c4c
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/mod.rs
@@ -0,0 +1,2483 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # The Wavelet
+//!
+//! > The traveler who fears the unknown road will eventually learn that known roads return
+//! > to where they began.
+//! >
+//! > - Anthony L. Ray
+//!
+//! ```text
+//! ·
+//! ·
+//! ·●
+//! ●
+//! •●
+//! •·
+//! ●···
+//! ●●●··
+//! ●●●●
+//! ●•••
+//! ···••
+//! ······●●
+//! ····●●●●●●
+//! ●●●●●●●●●
+//! ••••••●●
+//! •••·······
+//! ●●●●···········
+//! ●●●●●●●●●●·······
+//! ●●●●●●●●●●●●●
+//! ●●●••••••••
+//! ··········••••
+//! ··············●●●●●
+//! ·········●●●●●●●●●●●●
+//! ●●●●●●●●●●●●●●●
+//! •••••••••●●●
+//! •••••·········
+//! ●●●●··············
+//! ●●●●●●●●●●●········
+//! ●●●●●●●●●●●●●
+//! ●●●•••••••
+//! ·······••••
+//! ··········●●●
+//! ······●●●●●●●●
+//! ●●●●●●●●●
+//! ••••●●
+//! ••····
+//! ●●·····
+//! ●●●●···
+//! ●●●●
+//! ●••
+//! ··•
+//! ··●
+//! ·●●
+//! ●
+//! •
+//! ·
+//! ·
+//! ```
+//!
+//! This module generates families of wavelets for use in wavelet tables. Our wavelets are Morse
+//! family:
+//!
+//! - Easy to generate (reference IFFT method and high-precision
+//! [`QuadJet`](generate::quadjet::QuadJet) implementations available).
+//! - Fully analytic, one-sided response, making it nice for time and frequency reassignment
+//! - Very well studied, providing many closed-form analytic expressions that ease writing solvers
+//! or estimating tap lengths necessary to achieve performance goals.
+//! - Simple parameterization of time vs pitch precision tradeoffs.
+//!
+//! ## Usage
+//!
+//! Define a wavelet family with [`WaveletSpec`] and bake it into a [`Wavelet`]. Spec settings are
+//! maxima, and the bake is sized to serve every bin under them.
+//!
+//! ```
+//! # use mutate_lib::dsp::wavelet::WaveletSpec;
+//! let wavelet = WaveletSpec::default()
+//! .q(5.5)
+//! .max_truncation(-140.0)
+//! .bake();
+//! ```
+//!
+//! Resolve a bin with [`Wavelet::bin`] and realize its folded taps. Bins may use a tighter load
+//! quantum but may not exceed the [`Wavelet`].
+//!
+//! ```
+//! # use mutate_lib::dsp::wavelet::WaveletSpec;
+//! # let wavelet = WaveletSpec::default().q(5.5).max_truncation(-140.0).bake();
+//! let bin = wavelet.bin(440.0, 48_000.0).with_truncation(-100.0);
+//!
+//! // The `Bin` can be used to calculate allocation sizes.
+//! let mut taps = vec![[0.0f32; 4]; bin.len_folded()];
+//! bin.taps_into(&mut taps);
+//!
+//! // float4(Re ψ, Im ψ, Re d, Im d); index 0 is the real center tap.
+//! assert!(taps[0][1] == 0.0 && taps[0][3] == 0.0);
+//! ```
+//!
+//! ## Customizing the Wavelet Family
+//!
+//! The primary knobs are [`WaveletSpec::max_truncation`] and [`WaveletSpec::with_shape`], which modulate
+//! filter length, bandwidth, stop band, and skirt depth. All are inherently coupled. At a fixed
+//! filter length, raising Q while truncating harder (smaller magnitude of tail dB) trades time
+//! precision for pitch precision for likely a bit of noise floor.
+//!
+//! The `max_load_quantum` adjusts truncation and conditioning to land the mirrored tap length
+//! (excluding center tap!) on a quantum matching the size you intend to load. The center tap is
+//! usually loaded individually for a final reduction, also giving us an **odd tap invariant**.
+//!
+//! **Example:**
+//!
+//! - Implementation loads eight weights at a time for use in evaluating sixteen unfolded taps.
+//! - The if truncation for the configured options would normally lead to 17 *folded* weights, the
+//! implementation will round up to 24 instead, meaning 48 *unfolded* taps and 49 including the
+//! center.
+//! - The extra weights are used to shape truncation less aggressively, increasing precision and
+//! hopefully de-correlating some locally biased response to transients, diffusing artifacts.
+//!
+//! Setting [`max_load_quantum`] tells the motherlet (mother wavelet) to bake a longer grid so that
+//! if a wavelet's length is rounded up, there is enough grid to fill the `N` taps.
+//!
+//! ```
+//! # use mutate_lib::dsp::wavelet::WaveletSpec;
+//! # let wavelet = WaveletSpec::default()
+//! # .q(5.5)
+//! # .max_truncation(-140.0)
+//! # .max_load_quantum(32)
+//! # .bake();
+//! let bin = wavelet.bin(240.0, 3_000.0)
+//! .with_load_quantum(32);
+//!
+//! let mut taps = vec![[0.0f32; 4]; bin.len_folded()];
+//! let wrote = bin.taps_into(&mut taps);
+//!
+//! // mirrored half lands on the quantum, center tap excluded
+//! assert!((wrote - 1) % 32 == 0);
+//! ```
+//!
+//! ## Weight Table Format
+//!
+//! To support both pitch and time reassignment, we need three channels:
+//!
+//! | symbol | Rust | object | units | frame |
+//! |---|---|---|---|---|
+//! | `ψ` | `psi` | the wavelet | — | `u` |
+//! | `d` || `−(i/2π)·dψ/du`, the rotated derivative for pitch reassignment | dimensionless | `u` |
+//! | `t` || `ν·ψ(ρν)`, the wavelet's first moment kernel for time reassignment | samples | `ν` |
+//!
+//! Every wavelet uses an odd number of taps and each tap carries three weights, but we exploit the
+//! following relations:
+//!
+//! - `ψ` is Hermitian.
+//! - `−(i/2π)·dψ/du` is the rotated derivative and therefore also Hermitian.
+//! - `ν·ψ(νρ)` is anti-Hermitian. It carries `ν`, so `t` reads the same two half-pair
+//! products with the roles exchanged, `dif` against `Re ψ` and `sum` against `Im ψ`.
+//!
+//! So we fold `ψ` and `d` as sums and use `k` to derive `t` as the difference of the same products.
+//! The resulting table is `(N + 1)/2` entries of four floats, laid out as a Slang `float4` in the
+//! order `(Re ψ, Im ψ, Re d, Im d)`. The center tap is real in both channels, `(Re ψ₀, 0, Re d₀,
+//! 0)`, and contributes nothing to `t`.
+//!
+//! ## Generation Pipeline
+//!
+//! Low quality wavelets can cause many bad things that good things cannot fix. A principled
+//! approach upstream is required. We can divide the strategy into five phases:
+//!
+//! - Define coherent goals, such as `load_quantum` and `Q`, obtaining a [`WaveletSpec`].
+//! - Generate high resolution mother wavelet sufficient to fill any tap count that a [`BinSpec`]
+//! may need.
+//! - Dilate and truncate the mother wavelet to the length required to fill `N` taps with a
+//! [Restriction](restrict::Restriction) operator (fancy downsampling) squeezing the high
+//! resolution mother wavelet into the coarse `N` taps.
+//! - [Taper](restrict::Taper) the truncation to lessen the spectral damage of the cliff and obtain
+//! a better starting point for refinement.
+//! - [Refine](refile::Refinement) the final result to restore certain analytic properties such as
+//! moments and peak curvature while taking liberties to clean up spectral artifacts and enhance
+//! transient response where possible.
+//!
+//! Everything before refinement is almost purely driven by time-domain geometry. Refinement itself
+//! is the first spectrally aware step. The derivative generation is downstream of all work on `Ψ`.
+//! The time derivative is re-generated from the other taps on the fly and therefore only concretely
+//! exists at the point of use.
+//!
+//! ## Symbols and Nomenclature
+//!
+//! Unrealized wavelets are frequently handled using period normalized coordinates, `u` periods from
+//! the center. Only when realizing a [`Bin`] into memory do frequency `fs` and center
+//! frequency `fc` appear. The concrete using the appropriate `ρ` period density.
+//!
+//! ### Coordinates
+//!
+//! Wavelets are created and dilated using the real coordinate and mapped to and from integral
+//! indexed grids using `ρ`, periods per tap or grid sample (depends on context, but the choice is
+//! always obvious).
+//!
+//! | symbol | variable | object | units |
+//! |---|---|---|---|
+//! | `u` || periods from the wavelet's center, a real | carrier periods |
+//! | `ρ` | `rho` | the conversion ratio, a linear density | periods per tap |
+//!
+//! `resolution` is the number of grid points per period `u` and decides how finely each period of
+//! the mother wavelet will be resolved before restriction to `N` taps.
+//!
+//! `ρ` was intended to only be used when converting `u` periods to grid or sample points, but the
+//! same `ρ` in context turns out to be identical to `fc/fs` and a convenient way to write `ω` from
+//! `(0.0,0.5)` where `ρ = 0.5` is a function of the Nyquist, no `2π` in sight.
+//!
+//! There are additionally three integral coordinates distinguished by the use case:
+//!
+//! | symbol | variable | object | units |
+//! |---|---|---|---|
+//! | `m` || center sample index of the analysis window, the origin | samples |
+//! | `ν` | `nu` | signed integer tap index relative to `m`, in `(-K, K)` | taps |
+//! | `k` || taps from the center tap, in `[0, K)` and only used for symmetric work | taps |
+//! | `n` || unfolded tap index, `n = ν + K − 1` on `[0, N)` | taps |
+//!
+//! - `n` is used for indexing unfolded taps, such as for computering DFTs of filters for tests.
+//! - `m` shows back up in shaders as the index of the center tap sample. That anchors the analysis
+//! window for each hop.
+//! - `k` makes the most sense when modifying taps since there are not actually two distinct taps,
+//! while `nu` makes the most sense when using taps, where lane assignment will use `m` for the
+//! center index.
+//!
+//! ### Projections
+//!
+//! Correlations of the signal `x` against each channel about center `m`.
+//!
+//! | symbol | variable | object |
+//! |---|---|---|
+//! | `Ψ` | `psi_sum` | `Σ_ν conj(ψ_ν)·x_{m+ν}` |
+//! | `D` | `d_sum` | the same sum against `d_ν` |
+//! | `T` | `t_sum` | the same sum against `t_ν` |
+//!
+//! ### Estimators
+//!
+//! | symbol | variable | object | units | frame |
+//! |---|---|---|---|---|
+//! | `r̂` | `r_hat` | `Re(D/Ψ)`, the detuning | multiples of the carrier | `u` |
+//! | `t̂` | `t_hat` | `m + Re(T/Ψ)`, reassigned time | samples | `ν` |
+//!
+//! Each inherits its channel's frame. `t̂` is already on the output grid. `r̂` reaches physical
+//! frequency through `f = r̂·f_c`, and bank placement wants `log2 r̂`.
+//!
+//! ## Sample Computation
+//!
+//! Unpack weights and obtain `r_hat` and `t_hat`.
+//!
+//! ```slang
+//! // per hop, K = (N + 1)/2 entries, w[k] = (Re ψ, Im ψ, Re d, Im d)
+//! float2 psi = float2(w[0].x, 0.0) * x[m];
+//! float2 dee = float2(w[0].z, 0.0) * x[m];
+//! float2 tee = float2(0.0, 0.0);
+//!
+//! for (uint k = 1; k < K; ++k) {
+//! float sum = x[m + k] + x[m - k];
+//! float dif = x[m + k] - x[m - k];
+//! float4 c = w[k];
+//!
+//! psi += float2( c.x * sum, -c.y * dif);
+//! dee += float2( c.z * sum, -c.w * dif);
+//! tee += float(k) * float2( c.x * dif, -c.y * sum);
+//! }
+//!
+//! // Re(D·conj Ψ)/|Ψ|² and Re(T·conj Ψ)/|Ψ|²
+//! float inv = 1.0 / dot(psi, psi);
+//! float r_hat = dot(dee, psi) * inv;
+//! float t_hat = float(m) + dot(tee, psi) * inv;
+//! ```
+//!
+//! ## Compute & Register Cost
+//!
+//! - 5 ops per tap
+//! - 4 f32s per 2 mirrored taps, 2 per tap
+//! - 3 (W_ψ, W_d, W_t) complex accumulators, 6 registers per pipelined hop.
+//!
+//! For `P` pipelines, we need `6P + 6 + 2` non-uniform registers per lane and some scratch for
+//! temporaries. Audio is 8 bytes per sample at two channels and each 8 bytes of audio read can be
+//! re-used for `P` taps for each read. Each mirrored tap applies to two audio samples per
+//! pipelined hop.
+
+// #![warn(warnings, dead_code, unused_variables)]
+
+// 🤖 Heavy generation all over this module. Should be pretty standard academic stuff, so not
+// expecting a lot of surprises. We will, for the most part, swiftly and knowingly eat shit if the
+// wavelet is busted. Well-formalized stuff doesn't have a lot of wiggle room to violate the
+// consistency of the formalism.
+
+// DEBT Redundant code check identified a lot of places to improve. Reading this? It's still time.
+// DEBT The newer `max_rho` and `max_noise_floor` API replacing `truncation` and `tail_db` needs to
+// be migrated. Unfortunately this affects basically all tests. Most will adapt smoothly. Fix up
+// the mapping constant in spec while you're at it. 🤖
+// MAYBE The `d` provided for Hermite interpolation is basically not used at all for the actual `N`
+// tap outputs. It may be appropriate to remove the turn from everywhere upstream of `taps_into`,
+// but that's also a ton of little edits that I want to think about before committing to. Obvious
+// LLM task. Tell the young, impressionable puritans to cry more into my cup.
+// MAYBE A ton of the characterization gear for testing belongs higher in the dsp module?
+// NEXT High omega filters, starting at around 60% of Nyquist, begin to degrade at low Q. The
+// carrier doesn't have enough detail to represent a fast-changing envelope. A numerical solution
+// for these heavily aliased wavelets may succeed or we may use a Plan with a higher Q beyond some
+// empirical cutoff. Truncating less aggressively can't help because the main lobe itself is
+// dominating the breakdown. The Weighted quadrature might be helpful if its drawbacks (center is
+// not precise) can be mitigated.
+// NOTE We have logarithmic bin spacings, but the cutoff frequencies that determine which downsample
+// will be used are not particularly aware, so it's not expected that we can re-use exact bins in
+// any kind of octave structure. Mel scaling etc also defeats this, so there's no point.
+
+// === TABLE RESPONSE (Q = 3.5, quantum 8) ===
+//
+// fc 1000 fs 6000 w0 1.047198 quantized 25 (unfolded 49)
+// peak gain 2.000000032 dev +1.578e-8 rel
+// width 0.99725
+// peak -0.0125 cents
+// image max -111.29 dB
+// stopband floor -109.30 dB
+//
+// fc 250 fs 3000 w0 0.523599 quantized 49 (unfolded 97)
+// peak gain 2.000000003 dev +1.666e-9 rel
+// width 0.99838
+// peak -0.0164 cents
+// image max -110.83 dB
+// stopband floor -106.17 dB
+//
+// fc 12000 fs 48000 w0 1.570796 quantized 17 (unfolded 33)
+// peak gain 1.999999994 dev -3.209e-9 rel
+// width 0.99550
+// peak -0.0088 cents
+// image max -111.95 dB
+// stopband floor -108.55 dB
+
+
+mod calibrate;
+mod generate;
+mod inspect;
+mod refine;
+mod restrict;
+mod spec;
+// NEXT Whatsleft is ready to go into a crate, on the way to becoming its own repo.
+pub mod whatsleft;
+
+#[cfg(test)]
+mod harness;
+#[cfg(test)]
+mod tests {
+ mod print;
+ mod smoke;
+}
+
+use core::f64::consts::{PI, TAU};
+
+use num_complex::Complex64;
+
+use generate::hermite;
+use inspect::{Inspect, Sample, OVERSAMPLE};
+use spec::TAIL_OVER_FLOOR_DB;
+pub use spec::{BinSpec, Shape, WaveletSpec};
+
+pub mod defaults {
+ #[cfg(debug_assertions)]
+ pub const RESOLUTION: usize = 64;
+ #[cfg(not(debug_assertions))]
+ pub const RESOLUTION: usize = 128;
+
+ pub const DELAY: usize = 0;
+ pub const GAMMA: f64 = 2.0;
+ pub const GRID_EPS: f64 = 1e-9;
+ pub const LOAD_QUANTUM: usize = 4;
+ pub const Q: f64 = 3.5;
+ pub const NOISE_FLOOR: f64 = -70.0;
+}
+
+/// Filter peak gain. Analytic taps see half a real tone's amplitude, so |H| = 2 makes a unit tone
+/// read |W| = 1.
+const PEAK_GAIN: f64 = 2.0;
+
+/// The mother wavelet (aka Motherlet®) that has been densely sampled and can serve every [`Bin`]
+/// sharing a [`Shape`], up to the maxima specified in the [`WaveletSpec`].
+pub struct Wavelet {
+ shape: Shape,
+ /// Periods per grid point.
+ du: f64,
+ /// Ψ
+ psi: Vec,
+ /// Rotated (for symmetry) derivative, `−(i/2π)·dψ/du`.
+ d: Vec,
+ /// Bin defaults, and the ceiling the grid extent was sized against.
+ limits: BinSpec,
+ /// Strategy for reducing grid to `N` taps.
+ restriction: restrict::Restriction,
+ /// Strategy for refining the post-restiction spectral and analytic characteristics.
+ refinement: Option,
+}
+
+impl Wavelet {
+ /// Return a `Bin` definition that may be used to bake `N` taps into some destination memory.
+ /// New bin will use the limits from the `WaveletSpec`
+ pub fn bin(&self, center: f64, rate: f64) -> Bin<'_> {
+ Bin::new(
+ self,
+ BinSpec {
+ center,
+ rate,
+ ..self.limits
+ },
+ )
+ }
+
+ // XXX Not so sure about this API
+ /// Return a bin at `rho` with `half` folded weights past the center.
+ pub fn at_reach(&self, rho: f64, half: usize) -> Bin<'_> {
+ Bin {
+ wavelet: self,
+ spec: BinSpec {
+ center: rho,
+ rate: 1.0,
+ ..self.limits
+ },
+ rho,
+ k: half + 1,
+ }
+ }
+
+ pub fn from_spec(&self, spec: BinSpec) -> Bin<'_> {
+ Bin::new(self, spec)
+ }
+
+ /// A bin named by ρ directly, periods per tap. `bin(fc, fs)` is `at_rho(fc / fs)`.
+ pub fn at_rho(&self, rho: f64) -> Bin<'_> {
+ self.bin(rho, 1.0)
+ }
+
+ pub fn shape(&self) -> Shape {
+ self.shape
+ }
+
+ pub fn restriction(&self) -> restrict::Restriction {
+ self.restriction
+ }
+
+ fn grid(&self) -> Grid<'_> {
+ Grid {
+ psi: &self.psi,
+ d: &self.d,
+ du: self.du,
+ shape: self.shape,
+ }
+ }
+}
+
+/// The baked motherlet, resolved on `u`.
+#[derive(Clone, Copy)]
+struct Grid<'w> {
+ pub psi: &'w [Complex64],
+ pub d: &'w [Complex64],
+ pub du: f64,
+ pub shape: Shape,
+}
+
+impl<'w> Grid<'w> {
+ pub fn at(&self, u: f64) -> Complex64 {
+ hermite::eval(self.psi, self.d, u, self.du)
+ }
+
+ pub fn mass(&self, u_beg: f64, u_end: f64) -> Complex64 {
+ hermite::integrate(self.psi, self.d, u_beg, u_end, self.du)
+ }
+}
+
+/// A spec resolved against one bake. Carrying the borrow keeps a bin off the wrong motherlet,
+/// where the tap count would be wrong outright.
+#[derive(Clone, Copy)]
+pub struct Bin<'w> {
+ wavelet: &'w Wavelet,
+ spec: BinSpec,
+ /// Periods per tap, `fc / fs`. The only bridge from sample rate into `u`.
+ rho: f64,
+ /// Folded weights including the center tap.
+ k: usize,
+}
+
+impl<'w> Bin<'w> {
+ fn new(wavelet: &'w Wavelet, spec: BinSpec) -> Self {
+ let l = wavelet.limits;
+ let rho = spec.center / spec.rate;
+
+ debug_assert!(rho <= l.center, "rho {rho} over the wavelet's {}", l.center);
+ debug_assert!(
+ spec.noise_floor >= l.noise_floor,
+ "noise floor {} under the wavelet's {}",
+ spec.noise_floor,
+ l.noise_floor
+ );
+ debug_assert!(spec.load_quantum <= l.load_quantum);
+ debug_assert!(spec.delay <= l.delay);
+
+ let tail_db = spec.noise_floor - TAIL_OVER_FLOOR_DB;
+ // K, where the taper reaches zero at or past u
+ let edge = (wavelet.shape.truncation_u(tail_db) / rho).ceil() as usize;
+ let half = (edge - 1 + spec.delay).div_ceil(spec.load_quantum) * spec.load_quantum;
+
+ Bin {
+ wavelet,
+ spec,
+ rho,
+ k: half + 1,
+ }
+ }
+
+ /// Set the bin's delay. Must respect `Wavelet` limits.
+ pub fn with_delay(self, delay: usize) -> Self {
+ Self::new(self.wavelet, BinSpec { delay, ..self.spec })
+ }
+
+ /// Set the bin's load quantum. Must respect `Wavelet` limits.
+ pub fn with_load_quantum(self, load_quantum: usize) -> Self {
+ Self::new(
+ self.wavelet,
+ BinSpec {
+ load_quantum,
+ ..self.spec
+ },
+ )
+ }
+
+ pub fn with_noise_floor(self, db: f64) -> Self {
+ Self::new(
+ self.wavelet,
+ BinSpec {
+ noise_floor: -db.abs(),
+ ..self.spec
+ },
+ )
+ }
+
+ /// Set the bin's center frequency, using its sample rate multiplied by the periods-per-sample
+ /// density, `rho`.
+ pub fn with_rho(self, rho: f64) -> Self {
+ let center = self.spec.rate * rho;
+ Self::new(
+ self.wavelet,
+ BinSpec {
+ center,
+ ..self.spec
+ },
+ )
+ }
+
+ /// Set the bin's tail dB. Must respect `Wavelet` limits.
+ pub fn with_truncation(self, tail_db: f64) -> Self {
+ self.with_noise_floor(tail_db.abs() - TAIL_OVER_FLOOR_DB)
+ }
+
+ /// truncation_tail(ρK)
+ pub fn tail(&self) -> f64 {
+ self.wavelet.shape.truncation_tail(self.rho * self.k as f64)
+ }
+
+ /// Options used to create this bin.
+ pub fn spec(&self) -> BinSpec {
+ self.spec
+ }
+
+ /// Radians per tap. `ω₀ = 2π·ρ`
+ pub fn velocity(&self) -> f64 {
+ TAU * self.rho
+ }
+
+ /// Periods per tap.
+ pub fn rho(&self) -> f64 {
+ self.rho
+ }
+
+ /// Number of folded weights, including a center tap weighs. `K = (N + 1) / 2`.
+ pub fn len_folded(&self) -> usize {
+ self.k
+ }
+
+ /// Number of real taps after weights are unfolded. `2K - 1`. Center tap is still just one
+ /// tap.
+ pub fn len_unfolded(&self) -> usize {
+ 2 * self.k - 1
+ }
+
+ /// ψ and d for this bin, normalized at the measured crest of |H|.
+ ///
+ /// ```text
+ /// H(ω_peak) = PEAK_GAIN
+ /// H_d(ω) ≈ (ω/ω₀)·H(ω)
+ /// ```
+ pub fn write(&self, bake: &mut Bake) {
+ let (wav, rho, w0) = (self.wavelet, self.rho, self.velocity());
+ let Bake { weights: w, probe } = bake;
+
+ w.resize(self.k);
+ wav.restriction.psi_into(wav.grid(), rho, &mut w.psi);
+ debug_assert!(
+ w.psi.iter().all(|p| p.is_finite()),
+ "restriction produced a non-finite weight at rho {rho}"
+ );
+
+ if let Some(refinement) = wav.refinement {
+ refinement.apply(&mut w.psi, wav.shape, rho);
+ }
+
+ // ω_peak and H(ω_peak)
+ let (peak, gain) = Inspect::new(w.psi(), probe, OVERSAMPLE)
+ .peak(w0, 0.0, PI)
+ .unwrap_or((w0, w.psi().dtft(w0)));
+
+ let scale = PEAK_GAIN / gain;
+ for p in w.psi.iter_mut() {
+ *p *= scale;
+ }
+
+ wav.restriction
+ .derivative
+ .write(&w.psi, peak / TAU, w0, &mut w.d);
+ }
+
+ /// Upstream owes an `out` at least `folded_taps()` long.
+ pub fn taps_into(&self, out: &mut [[f32; 4]]) -> usize {
+ let mut bake = Bake::default();
+ self.write(&mut bake);
+ bake.weights.pack_into(out)
+ }
+
+ /// Only used by storage format aware consumers.
+ pub fn taps(&self) -> Vec<[f32; 4]> {
+ let mut out = vec![[0.0f32; 4]; self.k];
+ self.taps_into(&mut out);
+ out
+ }
+
+ /// Write the bin to an owned vector and and return it as a [`Weights]` for inspection.
+ pub fn weights(&self) -> Weights {
+ Weights::unpack(&self.taps())
+ }
+}
+
+/// Folded ψ and d for one bin.
+#[derive(Default)]
+pub struct Weights {
+ psi: Vec,
+ d: Vec,
+}
+
+impl Weights {
+ pub(self) fn psi(&self) -> Fold<'_> {
+ Fold::new(&self.psi)
+ }
+
+ #[cfg(test)]
+ pub(self) fn d(&self) -> Fold<'_> {
+ Fold::new(&self.d)
+ }
+
+ fn resize(&mut self, k: usize) {
+ self.psi.clear();
+ self.d.clear();
+ self.psi.resize(k, Complex64::default());
+ self.d.resize(k, Complex64::default());
+ }
+
+ /// float4(Re ψ, Im ψ, Re d, Im d), index 0 real in both lanes.
+ pub fn pack_into(&self, out: &mut [[f32; 4]]) -> usize {
+ let k = self.psi.len();
+ out[0] = [self.psi[0].re, 0.0, self.d[0].re, 0.0].map(|v| v as f32);
+ for (o, (p, q)) in out[1..k]
+ .iter_mut()
+ .zip(self.psi[1..].iter().zip(&self.d[1..]))
+ {
+ *o = [p.re, p.im, q.re, q.im].map(|v| v as f32);
+ }
+ k
+ }
+
+ /// Lanes recovered from a packed table, carrying its f32 rounding.
+ pub fn unpack(table: &[[f32; 4]]) -> Self {
+ let lane = |c: usize| {
+ table
+ .iter()
+ .map(|w| Complex64::new(w[c] as f64, w[c + 1] as f64))
+ .collect()
+ };
+ Weights {
+ psi: lane(0),
+ d: lane(2),
+ }
+ }
+
+ /// Ψ, D, T about center `m`, accumulated as the shader does.
+ #[cfg(test)]
+ pub(super) fn project(&self, x: impl Fn(isize) -> f64, m: isize) -> [Complex64; 3] {
+ let x0 = x(m);
+ let mut psi = Complex64::new(self.psi[0].re * x0, 0.0);
+ let mut dee = Complex64::new(self.d[0].re * x0, 0.0);
+ let mut tee = Complex64::default();
+
+ for (j, (p, q)) in self.psi[1..].iter().zip(&self.d[1..]).enumerate() {
+ let k = j as isize + 1;
+ let (hi, lo) = (x(m + k), x(m - k));
+ let (sum, dif) = (hi + lo, hi - lo);
+
+ psi += Complex64::new(p.re * sum, -p.im * dif);
+ dee += Complex64::new(q.re * sum, -q.im * dif);
+ tee += k as f64 * Complex64::new(p.re * dif, -p.im * sum);
+ }
+ [psi, dee, tee]
+ }
+}
+
+/// Reusable scratch for filling bins. Separate fields so the probe stays borrowable while the
+/// weights are being read.
+#[derive(Default)]
+pub struct Bake {
+ weights: Weights,
+ probe: Vec,
+}
+
+impl Bake {
+ pub fn weights(&self) -> &Weights {
+ &self.weights
+ }
+}
+
+/// A borrowed view of a single channel of [`Weights`].
+///
+/// `ψ` indexed over `[0, K)`, the mirror `ψ₋ₖ = conj ψₖ` implied. Entry 0 is real.
+// Making the channel first class could prevent some kinds of mishandling
+#[derive(Clone, Copy)]
+pub(super) struct Fold<'a>(&'a [Complex64]);
+
+impl<'a> Fold<'a> {
+ pub(self) fn new(psi: &'a [Complex64]) -> Self {
+ Fold(psi)
+ }
+
+ /// Number of real taps after weights are unfolded, in `[0, 2K - 1]`. Center tap is still just
+ /// one tap.
+ pub fn len_unfolded(&self) -> usize {
+ 2 * self.0.len() - 1
+ }
+
+ /// Number of physical weights that unfold into taps. Includes a center weight. Always equal to `K`.
+ #[allow(unused)]
+ pub fn len_folded(&self) -> usize {
+ self.0.len()
+ }
+
+ /// `ψ₀ + 2 Σ_{k≥1} Re(ψ_k e^{−iωk})`
+ pub(self) fn dtft(&self, w: f64) -> f64 {
+ // k = LANES·b + i + 1
+ const LANES: usize = 16;
+
+ // e^{−iω(i+1)}
+ let mut lane = [Complex64::default(); LANES];
+ for i in 0..LANES {
+ lane[i] = Complex64::from_polar(1.0, -w * (i + 1) as f64);
+ }
+ // e^{−iω·LANES}
+ let block = lane[LANES - 1];
+
+ let (mut a_re, mut a_im) = ([0.0; LANES], [0.0; LANES]);
+ let (mut b_re, mut b_im) = ([0.0; LANES], [0.0; LANES]);
+ let mut phi = Complex64::new(1.0, 0.0);
+
+ let (blocks, tail) = self.0[1..].as_chunks::();
+
+ for c in blocks {
+ for i in 0..LANES {
+ a_re[i] += phi.re * c[i].re;
+ a_im[i] += phi.re * c[i].im;
+ b_re[i] += phi.im * c[i].re;
+ b_im[i] += phi.im * c[i].im;
+ }
+ phi *= block;
+ // Newton step toward |phi| = 1
+ phi *= 0.5 * (3.0 - phi.norm_sqr());
+ }
+
+ for (i, h) in tail.iter().enumerate() {
+ a_re[i] += phi.re * h.re;
+ a_im[i] += phi.re * h.im;
+ b_re[i] += phi.im * h.re;
+ b_im[i] += phi.im * h.im;
+ }
+
+ // cos(ωk) = pc − qs, sin(ωk) = −(ps + qc)
+ let mut sum = 0.0;
+ for i in 0..LANES {
+ let (c, s) = (lane[i].re, lane[i].im);
+ sum += a_re[i] * c - b_re[i] * s - a_im[i] * s - b_im[i] * c;
+ }
+
+ self.0[0].re + 2.0 * sum
+ }
+
+ /// M_p = Σ_ν ν^p ψ_ν
+ #[cfg(test)]
+ pub(self) fn moment(&self, p: i32) -> Complex64 {
+ let head = match p {
+ 0 => self.0[0],
+ _ => Complex64::default(),
+ };
+ self.0[1..].iter().enumerate().fold(head, |m, (j, h)| {
+ let w = 2.0 * ((j + 1) as f64).powi(p);
+ m + w * match p % 2 == 0 {
+ true => Complex64::new(h.re, 0.0),
+ false => Complex64::new(0.0, h.im),
+ }
+ })
+ }
+
+ /// A_p = Σ_ν |ν|^p |ψ_ν|
+ #[cfg(test)]
+ pub(self) fn abs_moment(&self, p: i32) -> f64 {
+ let head = match p {
+ 0 => self.0[0].norm(),
+ _ => 0.0,
+ };
+ head + 2.0
+ * self.0[1..]
+ .iter()
+ .enumerate()
+ .map(|(j, h)| ((j + 1) as f64).powi(p) * h.norm())
+ .sum::()
+ }
+
+ /// Σ_ν |ψ_ν|
+ #[cfg(test)]
+ pub(self) fn l1(&self) -> f64 {
+ self.0[0].norm() + 2.0 * self.0[1..].iter().map(|h| h.norm()).sum::()
+ }
+
+ /// Σ_ν |ψ_ν|²
+ #[cfg(test)]
+ pub(self) fn energy(&self) -> f64 {
+ self.0[0].norm_sqr() + 2.0 * self.0[1..].iter().map(|h| h.norm_sqr()).sum::()
+ }
+
+ /// Variance of the magnitude envelope.
+ ///
+ /// Σ ν²|ψ_ν| / Σ |ψ_ν|
+ #[cfg(test)]
+ pub(self) fn envelope_var(&self) -> f64 {
+ let num: f64 = self.0[1..]
+ .iter()
+ .enumerate()
+ .map(|(j, h)| {
+ let k = (j + 1) as f64;
+ 2.0 * k * k * h.norm()
+ })
+ .sum();
+ num / self.l1()
+ }
+
+ /// ψ over [−K, K), for display.
+ #[cfg(test)]
+ pub(super) fn mirrored(&self) -> impl Iterator
- + '_ {
+ let tail = self.0[1..].iter().copied();
+ tail.clone()
+ .rev()
+ .map(|h| h.conj())
+ .chain(self.0.iter().copied())
+ }
+}
+
+// Proper location for this has become amorphous. Burn something when convenient.
+#[cfg(test)]
+fn fmt_e(x: f64) -> String {
+ if !x.is_finite() {
+ return format!("{x:>9}");
+ }
+ let s = format!("{x:+.2e}");
+ // split "±m.mme±dd" into mantissa and exponent, then zero-pad the exponent
+ let (mantissa, exp) = s.split_once('e').unwrap_or(("999", "999"));
+ let exp: i32 = exp.parse().unwrap();
+ format!("{mantissa}e{exp:+03}")
+}
+
+#[cfg(test)]
+mod test {
+ // DEBT a lot of the matrix code is becoming pretty redundant. It's simple, but every test
+ // builds a matrix slightly differently. See the `unit_tone_reads_unity` test for some raw
+ // harness ideas taking shape. It does a much more complete matrix than other tests and reports
+ // threshold headroom and total error mass.o
+ // DEBT the print tests are secretly being used in a manner that the workbench binary is
+ // intended for. As things are becoming mature enough, moving some features over to the
+ // workbench tools would be welcome, although it may need some redesign since basically all IIR
+ // solutions and therefore most of the tests with time dependency are DoA on the GPU.
+
+ use core::f64::consts::{LN_2, LOG2_10};
+
+ use super::*;
+
+ use harness::*;
+ use inspect::*;
+
+ const RATE: f64 = 48_000.0;
+ const WEAKEST_TAIL_DB: f64 = -160.0;
+
+ fn wavelet(q: f64, quantum: usize) -> Wavelet {
+ WaveletSpec::default()
+ .shape(Shape::from_q(q, 3.0))
+ .max_load_quantum(quantum)
+ .max_truncation(WEAKEST_TAIL_DB)
+ .bake()
+ }
+
+
+ /// Reassignment error over the detuning each bin is responsible for. A bank at `SPACING`
+ /// cents hands off at half that, so beyond it the reading belongs to a neighbor.
+ #[test]
+ fn reassignment_is_unbiased() {
+ const Q: f64 = 3.5;
+ const QUANTUM: usize = 4;
+ const TAIL_DB: f64 = -40.0;
+
+ const SPACING: f64 = 400.0;
+ const STEPS: isize = 8;
+ const RESOLUTION: f64 = 0.05;
+
+ /// Worst per hop error in cents, bias plus the swing across carrier phase.
+ const ERROR_C: f64 = 4.0;
+
+ const SKIRT_DB: f64 = -30.0;
+ const SKIRT_C: f64 = 20.0;
+ /// Reach of the crossing search, an octave either side.
+ const SPAN: f64 = 1.0;
+
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(Q, 3.0))
+ .max_load_quantum(QUANTUM)
+ .max_truncation(TAIL_DB)
+ .bake();
+
+ println!("\n=== REASSIGN ===");
+
+ for (fc, fs) in [
+ (2_000.0f64, RATE),
+ (200.0, 3000.0),
+ (250.0, 3000.0),
+ (12_000.0, RATE),
+ ] {
+ let bin = wav.at_rho(fc / fs);
+ let wts = bin.weights();
+ let (psi, d) = (wts.psi(), wts.d());
+
+ let (n, w0) = (psi.len_unfolded(), bin.velocity());
+ println!(" fc {fc:.0} fs {fs:.0} taps {n} w0 {w0:.6}");
+ println!(" detune |H| pred bias swing leak");
+
+ for k in -STEPS..=STEPS {
+ let cents = k as f64 * 0.5 * SPACING / STEPS as f64;
+ // 2^(c/1200)
+ let ratio = (cents / 1200.0).exp2();
+ let h = psi.dtft(w0 * ratio).abs();
+
+ let ((bias, swing), (leak, _)) = tone_bias(&wts, w0, cents, RESOLUTION);
+ let (_, dr) = pairing_residual(psi, d, w0, w0 * ratio);
+ // (1200 / ln 2) · Re(R/Ψ̂) / r
+ let pred = 1200.0 / LN_2 * dr / ratio;
+
+ println!(
+ " {cents:+6.1}c {:>7.1} {pred:>8.3}c {bias:>8.3}c {swing:>9.4}c {leak:>9.2e}",
+ 20.0 * (h / PEAK_GAIN).log10(),
+ );
+
+ assert!(
+ bias.abs() + swing < ERROR_C,
+ "fc {fc} detune {cents} error {:.4}c",
+ bias.abs() + swing
+ );
+ }
+
+ let peak = psi.dtft(w0).abs();
+ let (lo, hi) = shoulders(psi, peak, w0, SKIRT_DB, w0 * SPAN);
+
+ for w in [lo, hi].into_iter().flatten() {
+ // 1200 log2(ω/ω₀)
+ let cents = 1200.0 * (w / w0).log2();
+ let ((bias, swing), _) = tone_bias(&wts, w0, cents, RESOLUTION);
+ let worst = bias.abs() + swing;
+ println!(" skirt {cents:+7.1}c bias {bias:+8.3}c swing {swing:8.3}c");
+ assert!(
+ worst < SKIRT_C,
+ "fc {fc} skirt {cents:.1} worst {worst:.3}c"
+ );
+ }
+ }
+ }
+
+ /// PSL control through `Fit::CALIBRATED` against a full-length bake. Each target sets its
+ /// tail through `Fit::tail_for_psl`, and one motherlet serves the reference and every cut, so a
+ /// gap in the delta columns is truncation and nothing else.
+ #[test]
+ fn truncation_is_predictable() {
+ use super::calibrate::Fit;
+
+ const QUANTUM: usize = 1;
+ const Q: f64 = 3.5;
+
+ /// Weakest truncation in the sweep, and so the grid the wavelet is sized for.
+ const FULL_DB: f64 = -140.0;
+ /// PSL targets, set through `Fit::tail_for_psl`.
+ const TARGETS: [f64; 6] = [-40.0, -50.0, -60.0, -70.0, -90.0, -110.0];
+ /// Share of in-fold targets the PSL envelope must hold, `ENVELOPE` less slack off the ladder.
+ const HELD: f64 = 0.85;
+ const FCS: [f64; 4] = [2_000.0, 4_000.0, 8_000.0, 14_000.0];
+
+ // NOTE these are empirically discovered values stored to catch regressions.
+
+ // Measured 0.9984 to 1.0020 across the sweep.
+ const WIDTH_Q: f64 = 1.0;
+ const WIDTH_TOL: f64 = 0.02;
+
+ /// Spec at `fc` whose PSL envelope under `Fit::CALIBRATED` holds `psl` on `shape`.
+ fn spec_for_psl(shape: Shape, fc: f64, rate: f64, psl: f64) -> BinSpec {
+ BinSpec::new(fc, rate).truncate(Fit::CALIBRATED.tail_for_psl(shape, fc / rate, psl))
+ }
+
+ /// Tallest skirt lobe in dB re PEAK_GAIN, NaN where no lobe stands past a dip.
+ fn psl(psi: Fold<'_>, r: &Response) -> f64 {
+ let (lo, hi) = skirts(psi, r);
+ [lo.peak, hi.peak]
+ .into_iter()
+ .flatten()
+ .map(|(_, h)| db(h) - db(PEAK_GAIN))
+ .fold(f64::NAN, f64::max)
+ }
+
+ let w = WaveletSpec::default()
+ .shape(Shape::from_q(Q, 3.0))
+ .max_load_quantum(QUANTUM)
+ .max_truncation(FULL_DB)
+ .bake();
+
+ let to_peak = |v: f64| db(v) - db(PEAK_GAIN);
+ let cents = |w: f64, w0: f64| 1200.0 * (w / w0).log2();
+
+ println!(
+ "\n=== TRUNCATION (Q = {Q}, quantum {QUANTUM}) ===\n\n\
+ - |H| is the response to a unit exponential.\n\
+ - gain is |H| at the peak. peak c is the peak offset from ω₀ in cents.\n\
+ - dc, psl, image, and floor are in dB relative to PEAK_GAIN. image is the worst |H| on [−π, 0].\n\
+ - target is the PSL asked of Fit::CALIBRATED, tail the realized cut, miss is psl − target.\n\
+ - ratio is the tap count divided by the reference tap count."
+ );
+
+ // Reference
+ println!("\n reference, tail {FULL_DB:.1} dB");
+ println!(
+ " {:>6} {:>5} {:>9} {:>8} {:>9} {:>8} {:>8} {:>8} {:>8}",
+ "fc", "taps", "gain", "width·Q", "peak c", "dc", "psl", "image", "floor"
+ );
+
+ let mut refs = Vec::with_capacity(FCS.len());
+ for fc in FCS {
+ let full = w.bin(fc, RATE).with_truncation(FULL_DB);
+ let nf = full.len_unfolded();
+ let wts = full.weights();
+ let psi = wts.psi();
+
+ let w0 = full.velocity();
+ let rf = characterize(psi, w0);
+ let dcf = dc_leak(psi, w0);
+
+ println!(
+ " {fc:>6.0} {nf:>5} {:>9.6} {:>8.4} {:>+9.3} {:>8.2} {:>8.2} {:>8.2} {:>8.2}",
+ rf.gain,
+ rf.rel_width * Q,
+ cents(rf.peak_w, w0),
+ to_peak(dcf),
+ psl(psi, &rf),
+ to_peak(rf.image),
+ to_peak(rf.floor)
+ );
+
+ // Peak sits below ω₀ by the cell-average droop, gain rising as ½P²Δx².
+ assert!(
+ (rf.gain - 2.0).abs() < 1e-5,
+ "fc {fc} full gain {:.9}",
+ rf.gain
+ );
+ assert!(
+ dcf < 1e-5 * PEAK_GAIN,
+ "fc {fc} full dc {:.2} dB",
+ to_peak(dcf)
+ );
+
+ // -3 dB width is set by P = sqrt(beta*gamma) and Q = P/1.6651.
+ assert!(
+ (rf.rel_width * Q / WIDTH_Q - 1.0).abs() < WIDTH_TOL,
+ "fc {fc} width x Q {:.4}",
+ rf.rel_width * Q
+ );
+
+ refs.push((fc, nf, rf, w0));
+ }
+
+ // Cuts
+ println!(
+ "\n {:>6} {:>7} {:>7} {:>5} {:>6} {:>9} {:>8} {:>9} {:>8} {:>8} {:>7} {:>8} {:>8}",
+ "fc",
+ "target",
+ "tail",
+ "taps",
+ "ratio",
+ "gain",
+ "width·Q",
+ "peak c",
+ "dc",
+ "psl",
+ "miss",
+ "image",
+ "floor"
+ );
+
+ let (mut held, mut asked) = (0usize, 0usize);
+ for (fc, nf, rf, w0) in &refs {
+ let (fc, nf, w0) = (*fc, *nf, *w0);
+ let (mut prev_taps, mut prev_psl) = (0usize, f64::INFINITY);
+ let fold = w.shape().image_db(fc / RATE);
+
+ for target in TARGETS {
+ if fold > target {
+ println!(" {fc:>6.0} {target:>7.1} past the fold at {fold:.1} dB");
+ continue;
+ }
+
+ let cut = spec_for_psl(w.shape(), fc, RATE, target)
+ .load_quantum(QUANTUM)
+ .bin(&w);
+ let nc = cut.len_unfolded();
+ let wts = cut.weights();
+ let psi = wts.psi();
+ let rc = characterize(psi, w0);
+ let dc = dc_leak(psi, w0);
+ let seen = psl(psi, &rc);
+
+ asked += 1;
+ if !(seen > target) {
+ held += 1;
+ }
+
+ println!(
+ " {fc:>6.0} {target:>7.1} {:>7.1} {nc:>5} {:>6.3} {:>9.6} {:>8.4} {:>+9.3} \
+ {:>8.2} {seen:>8.2} {:>+7.2} {:>8.2} {:>8.2}",
+ cut.tail(),
+ nc as f64 / nf as f64,
+ rc.gain,
+ rc.rel_width * Q,
+ cents(rc.peak_w, w0),
+ to_peak(dc),
+ seen - target,
+ to_peak(rc.image),
+ to_peak(rc.floor)
+ );
+
+ // The band neither moves nor widens.
+ assert!(
+ (cents(rc.peak_w, w0) - cents(rf.peak_w, w0)).abs() < 8.0,
+ "fc {fc} target {target} peak moved {:+.4}c",
+ cents(rc.peak_w, w0) - cents(rf.peak_w, w0)
+ );
+ if target < -60.0 {
+ assert!(
+ (rc.rel_width / rf.rel_width - 1.0).abs() < 0.1,
+ "fc {fc} target {target} width {:+.3}%",
+ 100.0 * (rc.rel_width / rf.rel_width - 1.0)
+ );
+ }
+
+ // Gain near DC combines both positive and negative components, so use of PEAK_GAIN
+ // is apt here.
+ // ROLL DC centering
+ assert!(
+ dc < 1e-1 * PEAK_GAIN,
+ "fc {fc} target {target} dc {:.2} dB",
+ to_peak(dc)
+ );
+
+ // Deeper targets buy PSL with taps. Taps may hold under quantum rounding.
+ assert!(
+ nc >= prev_taps,
+ "fc {fc} target {target} taps {nc} < {prev_taps}"
+ );
+
+ // If taps goes up, PSL goes down
+ assert!(
+ (nc == prev_taps || seen < prev_psl),
+ "fc {fc} target {target} taps {prev_taps} -> {nc} without PSL gain: {} to {}",
+ prev_psl,
+ seen,
+ );
+ prev_psl = seen;
+
+ (prev_taps, prev_psl) = (nc, rc.floor);
+ }
+ println!();
+ }
+
+ println!(" PSL held on {held} of {asked} in-fold targets");
+ assert!(
+ held as f64 >= HELD * asked as f64,
+ "PSL held on {held} of {asked} in-fold targets"
+ );
+ }
+
+ /// Same four numbers as `response_is_characterized`, measured on the folded weight table.
+ /// Sweeps the load quantum, because the quantum pads the emitted half-span.
+ #[test]
+ fn table_response_is_characterized() {
+ const Q: f64 = 3.5;
+ const TAIL_DB: f64 = -75.0;
+
+ let w = wavelet(Q, 16);
+
+ for quantum in [2usize, 4, 8, 16] {
+ println!("\n=== TABLE RESPONSE (Q = {Q}, quantum {quantum}) ===");
+
+ for (fc, fs) in [(1000.0f64, 6000.0f64), (250.0, 3000.0), (12_000.0, RATE)] {
+ let bin = w
+ .bin(fc, fs)
+ .with_load_quantum(quantum)
+ .with_truncation(TAIL_DB);
+ let wts = bin.weights();
+
+ let w0 = bin.velocity();
+ let r = characterize(wts.psi(), w0);
+ let rel = |v: f64| db(v) - db(r.gain);
+
+ println!(
+ "\nfc {fc:>5.0} fs {fs:>5.0} w0 {w0:.6} quantized {:>3} (unfolded {:>3})",
+ bin.len_folded(),
+ bin.len_unfolded()
+ );
+ println!(
+ " peak gain {:.9} dev {:+.3e} rel",
+ r.gain,
+ r.gain / PEAK_GAIN - 1.0
+ );
+
+ println!(" width {:.5}", r.rel_width * Q);
+ println!(" peak {:+.4} cents", 1200.0 * (r.peak_w / w0).log2());
+ println!(" image max {:>8.2} dB", rel(r.image));
+ println!(" stopband floor {:>8.2} dB", rel(r.floor));
+ }
+ }
+ }
+
+ /// Main lobe ends, peak side lobes, and transition transport per side over Q × γ × ρ.
+ #[test]
+ fn skirt_is_characterized() {
+ const QS: [f64; 4] = [6.0, 8.0, 14.0, 20.0];
+ const GAMMAS: [f64; 2] = [3.0, 4.0];
+ const RHOS: Axis = Axis::LogLevels(&[0.058, 0.116, 0.189, 0.223, 0.384]);
+ const QUANTUM: usize = 4;
+ const TAIL_DB: f64 = -60.0;
+
+ const NAMES: [&str; 4] = ["spread W", "psl dB", "E·d lo dB", "E·d hi dB"];
+ const PRECISION: [usize; 4] = [3, 2, 2, 2];
+
+ println!(
+ "\n=== SKIRT (quantum {QUANTUM}, tail {TAIL_DB:.0} dB) ===\n\
+ offsets in −3 dB widths from the peak, levels in dB below the peak\n\
+ dips end the main lobe, psl is the tallest lobe past each dip\n\
+ floor is the maximum roll-off\n\
+ E·d is transport from each −3 dB edge to its PSL crest, dB re one −3 dB width\n\
+ lo and hi E·d share the lobe term and sum linearly to the two sided transport\n"
+ );
+ println!(
+ " {:>5} {:>4} {:>7} {:>5} {:>8} {:>8} {:>7} {:>7} \
+ {:>8} {:>7} {:>8} {:>7} {:>7} {:>7}",
+ "Q",
+ "𝛄",
+ "𝛒",
+ "taps",
+ "lo dip",
+ "hi dip",
+ "spread",
+ "floor",
+ "psl lo",
+ "off lo",
+ "psl hi",
+ "off hi",
+ "E·d lo",
+ "E·d hi"
+ );
+
+ // (Q, γ, (IQM, worst) per metric)
+ let mut summary = Vec::new();
+
+ for q in QS {
+ for gamma in GAMMAS {
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(q, gamma))
+ .max_load_quantum(QUANTUM)
+ .max_truncation(TAIL_DB)
+ .bake();
+
+ // (w, x) over ρ per metric
+ let mut readings: [Vec<(f64, f64)>; 4] = Default::default();
+
+ for (w, rho) in RHOS.levels() {
+ let bin = wav.at_rho(rho);
+ let wts = bin.weights();
+ let psi = wts.psi();
+ let r = characterize(psi, bin.velocity());
+ let lobe = r.edges.1 - r.edges.0;
+ let to_gain = |h: f64| db(h) - db(r.gain);
+
+ let (psl_lo, psl_hi) = skirts(psi, &r);
+ let (lo, hi) = (psl_lo.dip.map(|d| d.0), psl_hi.dip.map(|d| d.0));
+
+ let spread = lo.zip(hi).map(|(lo, hi)| (hi - lo) / lobe);
+ let psl = [psl_lo.peak, psl_hi.peak]
+ .into_iter()
+ .flatten()
+ .map(|p| to_gain(p.1))
+ .reduce(f64::max);
+ let (ed_lo, ed_hi) = transition_mass(psi, r.edges, &psl_lo, &psl_hi);
+
+ for (v, x) in readings.iter_mut().zip([spread, psl, ed_lo, ed_hi]) {
+ if let Some(x) = x {
+ v.push((w, x));
+ }
+ }
+
+ /// Offset of a dip in −3 dB widths, dash where the descent found none.
+ let off = |w: Option| match w {
+ Some(w) => format!("{:>+8.3}", (w - r.peak_w) / lobe),
+ None => format!("{:>8}", "—"),
+ };
+ /// Right aligned at `p` digits, dash where unmeasured.
+ let opt = |v: Option, width: usize, p: usize| match v {
+ Some(v) => format!("{v:>width$.p$}"),
+ None => format!("{:>width$}", "—"),
+ };
+ /// Level and offset of one skirt's tallest lobe.
+ let cols = |s: &Skirt| match s.peak {
+ Some((w, h)) => {
+ format!("{:>8.2} {:>+7.3}", to_gain(h), (w - r.peak_w) / lobe)
+ }
+ None => format!("{:>8} {:>7}", "—", "—"),
+ };
+
+ println!(
+ " {q:>5.1} {gamma:>4.1} {rho:>7.4} {:>5} {} {} {} {:>7.2} {} {} {} {}",
+ psi.len_unfolded(),
+ off(lo),
+ off(hi),
+ opt(spread, 7, 3),
+ to_gain(r.floor),
+ cols(&psl_lo),
+ cols(&psl_hi),
+ opt(ed_lo, 7, 2),
+ opt(ed_hi, 7, 2),
+ );
+
+ let reaches = |s: &Skirt| s.peak.is_some_and(|(_, h)| h >= r.gain);
+ assert!(
+ !reaches(&psl_lo) && !reaches(&psl_hi),
+ "Q {q} γ {gamma} ρ {rho} side lobe reaches the main lobe"
+ );
+ }
+
+ // (IQM, max) over log ρ
+ let stats = readings.map(|mut v| {
+ let worst = v.iter().map(|r| r.1).fold(f64::NEG_INFINITY, f64::max);
+ let (q1, q3) = (
+ weighted_quantile(&mut v, 0.25),
+ weighted_quantile(&mut v, 0.75),
+ );
+ // Σ w x / Σ w over q1 ≤ x ≤ q3
+ let (num, den) = v
+ .iter()
+ .filter(|r| r.1 >= q1 && r.1 <= q3)
+ .fold((0.0, 0.0), |(n, d), r| (n + r.0 * r.1, d + r.0));
+ (num / den, worst)
+ });
+
+ summary.push((q, gamma, stats));
+ println!();
+ }
+ }
+
+ // Worst over Q × γ
+ let worst: [(f64, f64); 4] = core::array::from_fn(|i| {
+ summary
+ .iter()
+ .fold((f64::NEG_INFINITY, f64::NEG_INFINITY), |(a, b), s| {
+ (a.max(s.2[i].0), b.max(s.2[i].1))
+ })
+ });
+
+ let rule = "=".repeat(88);
+ let cell = |(iqm, max): (f64, f64), p: usize| match iqm.is_finite() {
+ true => format!("{iqm:.p$} ({max:.p$})"),
+ false => "—".to_string(),
+ };
+ let row = |lead: String, stats: &[(f64, f64); 4]| {
+ print!(" {lead}");
+ for (s, p) in stats.iter().zip(PRECISION) {
+ print!(" {:>18}", cell(*s, p));
+ }
+ println!();
+ };
+
+ println!("\n {rule}");
+ println!(" SKIRT IQM over log ρ, worst in parentheses");
+ println!(" spread in −3 dB widths, psl and E·d in dB, higher is worse");
+ println!(" {rule}");
+ print!(" {:>5} {:>4}", "Q", "γ");
+ for n in NAMES {
+ print!(" {n:>18}");
+ }
+ println!();
+ for (q, gamma, stats) in &summary {
+ row(format!("{q:>5.1} {gamma:>4.1}"), stats);
+ }
+ println!(" {rule}");
+ row(format!("{:>10}", "worst"), &worst);
+ println!(" {rule}");
+ }
+
+ // Transport (time-reassignment mis-location) Tests
+
+ /// (|Ψ|², Re(T Ψ̄)) about `m`
+ fn moments(wts: &Weights, x: &dyn Fn(isize) -> f64, m: isize) -> (f64, f64) {
+ let [psi, _, tee] = wts.project(x, m);
+ (psi.norm_sqr(), (tee * psi.conj()).re)
+ }
+
+ /// About `n` hops on a uniform stride across [−r, r]
+ fn hops(r: f64, n: usize) -> impl Iterator
- {
+ let stride = (2.0 * r / (n - 1) as f64).ceil().max(1.0) as usize;
+ let r = r.ceil() as isize;
+ (-r..=r).step_by(stride)
+ }
+
+ /// {(q + ½) φ}
+ fn offset(q: usize) -> f64 {
+ const GOLDEN: f64 = 0.618_033_988_749_894_8;
+ ((q as f64 + 0.5) * GOLDEN).fract()
+ }
+
+ /// Prints a reassignment transport report and returns the median and worst row E·d, dB re one
+ /// period.
+ ///
+ /// Each row holds (ρ, taps, readings per family), a reading being (E, d) with d in carrier
+ /// periods. Families enter each row at unit energy, so a row's pooled E·d is their mean.
+ fn transport_report(
+ title: &str,
+ names: &[&str],
+ rows: &[(f64, usize, Vec>)],
+ limits: [f64; 2],
+ ) -> [f64; 2] {
+ /// Displacement thresholds, periods.
+ const BEYOND: [f64; 4] = [1e-3, 1e-2, 1e-1, 1.0];
+ /// Energy band edges, least displaced first.
+ const EDGES: [f64; 5] = [0.25, 0.5, 0.75, 0.99, 1.0];
+ const BAND_LABELS: [&str; 5] = ["0-25%", "25-50%", "50-75%", "75-99%", "99-100%"];
+
+ // Σ E d / Σ E
+ let e_d = |r: &[(f64, f64)]| {
+ let (ed, e) = r
+ .iter()
+ .fold((0.0, 0.0), |(ed, e), v| (ed + v.0 * v.1, e + v.0));
+ ed / e
+ };
+ // 10 log10 u
+ let db_u = |u: f64| 10.0 * u.max(f64::MIN_POSITIVE).log10();
+ // d below which fraction f of the energy lands
+ let quantile = |r: &[(f64, f64)], f: f64| weighted_quantile(&mut r.to_vec(), f);
+ let pooled_col = names.len() > 1;
+
+ println!("\n=== {title} ===");
+ println!(" E is reported energy |Ψ|², d is displacement ρ |t̂ − t| in carrier periods");
+ println!(" E·d = Σ E·d / Σ E, in dB re one period");
+ println!(" q3 and q99 are d in periods, below which 75% and 99% of E lands\n");
+
+ print!(" {:>7} {:>5}", "rho", "taps");
+ for n in names {
+ print!(" {n:>8}");
+ }
+ if pooled_col {
+ print!(" {:>8}", "pooled");
+ }
+ println!(" {:>9} {:>9}", "q3 d", "q99 d");
+ let cols = names.len() + pooled_col as usize;
+ println!(" {}", "-".repeat(13 + 9 * cols + 20));
+
+ // Rows
+ let mut all = Vec::new();
+ let mut row_ed = Vec::with_capacity(rows.len());
+ for (rho, taps, families) in rows {
+ let mut pooled = Vec::new();
+ print!(" {rho:>7.4} {taps:>5}");
+ for f in families {
+ let total: f64 = f.iter().map(|v| v.0).sum();
+ print!(" {:>8.2}", db_u(e_d(f)));
+ pooled.extend(f.iter().map(|&(e, d)| (e / total, d)));
+ }
+ let ed = e_d(&pooled);
+ if pooled_col {
+ print!(" {:>8.2}", db_u(ed));
+ }
+ println!(
+ " {:>9.2e} {:>9.2e}",
+ quantile(&pooled, 0.75),
+ quantile(&pooled, 0.99)
+ );
+ row_ed.push((*rho, ed));
+ all.extend(pooled);
+ }
+
+ // Row quartiles
+ let mut spread: Vec = row_ed.iter().map(|r| r.1).collect();
+ spread.sort_by(f64::total_cmp);
+ let at = |f: f64| db_u(spread[((spread.len() - 1) as f64 * f).round() as usize]);
+
+ println!("\n E·d quartiles over rows, dB re one period");
+ println!(" {:>8} {:>8} {:>8}", "q1", "median", "q3");
+ println!(" {:>8.2} {:>8.2} {:>8.2}", at(0.25), at(0.5), at(0.75));
+
+ // Row extremes
+ let by_ed = |a: &&(f64, f64), b: &&(f64, f64)| a.1.total_cmp(&b.1);
+ let (best_rho, best) = *row_ed.iter().min_by(by_ed).unwrap();
+ let (worst_rho, worst) = *row_ed.iter().max_by(by_ed).unwrap();
+
+ println!("\n E·d row extremes");
+ println!(" {:>8} {:>8} {:>8}", "", "rho", "dB");
+ println!(" {:>8} {best_rho:>8.4} {:>8.2}", "best", db_u(best));
+ println!(" {:>8} {worst_rho:>8.4} {:>8.2}", "worst", db_u(worst));
+
+ // Energy beyond each displacement
+ let total: f64 = all.iter().map(|v| v.0).sum();
+
+ println!("\n share of E displaced beyond d periods");
+ print!(" ");
+ for b in BEYOND {
+ print!(" {:>9}", format!(">{b:e}"));
+ }
+ print!("\n ");
+ for b in BEYOND {
+ // Σ_{d > b} E / Σ E
+ let share = all.iter().filter(|v| v.1 > b).map(|v| v.0).sum::() / total;
+ print!(" {:>8.3}%", 100.0 * share);
+ }
+ println!();
+
+ // Energy bands, least displaced first
+ all.sort_by(|a, b| a.1.total_cmp(&b.1));
+ let mut banded = [(0.0f64, 0.0f64, 0.0f64); EDGES.len()];
+ let mut acc = 0.0;
+ for &(e, d) in &all {
+ let b = EDGES
+ .partition_point(|&x| x <= (acc + 0.5 * e) / total)
+ .min(EDGES.len() - 1);
+ let o = &mut banded[b];
+ *o = (o.0 + e / total, d, o.2 + e * d / total);
+ acc += e;
+ }
+ let total_ed: f64 = banded.iter().map(|b| b.2).sum();
+
+ println!("\n E·d by energy band, bands sum to the mean row E·d");
+ println!(" E is the band's share of energy, d is displacement in periods");
+ println!(
+ " {:>8} {:>7} {:>10} {:>10} {:>10} {:>8} {:>7}",
+ "band", "E", "mean d", "max d", "E·d", "E·d dB", "% E·d"
+ );
+ for (l, (e, dmax, ed)) in BAND_LABELS.iter().zip(banded) {
+ println!(
+ " {l:>8} {:>6.1}% {:>10.2e} {dmax:>10.2e} {ed:>10.2e} {:>8.2} {:>6.1}%",
+ 100.0 * e,
+ ed / e,
+ db_u(ed),
+ 100.0 * ed / total_ed
+ );
+ }
+
+ // Headline
+ let measured = [at(0.5), db_u(worst)];
+ let verdict = |h: f64| if h > 0.0 { "pass" } else { "FAIL" };
+ let rule = "=".repeat(31);
+
+ println!("\n {rule}");
+ println!(" {:>9} {:>10} {:>10}", "E·d dB", "median row", "worst row");
+ println!(" {rule}");
+ println!(
+ " {:>9} {:>10.2} {:>10.2}",
+ "measured", measured[0], measured[1]
+ );
+ println!(" {:>9} {:>10.2} {:>10.2}", "limit", limits[0], limits[1]);
+ print!(" {:>9}", "headroom");
+ for (m, l) in measured.iter().zip(limits) {
+ print!(" {:>10.2}", l - m);
+ }
+ print!("\n {:>9}", "");
+ for (m, l) in measured.iter().zip(limits) {
+ print!(" {:>10}", verdict(l - m));
+ }
+ println!("\n {rule}");
+
+ measured
+ }
+
+ /// Energy that time reassignment moves off an impulse, and how far.
+ ///
+ /// E·d = Σ E ρ |t̂ − p| / Σ E
+ ///
+ /// A band-limited impulse at sub-sample `p` has exact truth at every hop. E = |Ψ|² is reported
+ /// energy and d is displacement in carrier periods, the dilation invariant frame.
+ #[test]
+ fn t_hat_impulse_transport() {
+ const Q: f64 = 3.5;
+ const GAMMA: f64 = 3.0;
+ const QUANTUM: usize = 4;
+ const TAIL_DB: f64 = -40.0;
+
+ const PITCHES: usize = 48;
+ const RHO_LO: f64 = 0.01;
+ const RHO_HI: f64 = 0.375;
+ const HOPS: usize = 64;
+ const PHASES: usize = 6;
+
+ const MEDIAN_DB: f64 = -35.0;
+ const WORST_DB: f64 = -10.0;
+
+ // XXX The refinement is not quite performing here or the test is not stressing the filter
+ // enough. No refinement outperforms the default refinement, which was not the case during
+ // most of development.
+
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(Q, GAMMA))
+ .max_load_quantum(QUANTUM)
+ .max_truncation(TAIL_DB)
+ .bake();
+
+ let rows: Vec<_> = (0..PITCHES)
+ .map(|i| {
+ // ρ_lo (ρ_hi / ρ_lo)^(i / (n − 1))
+ let rho = RHO_LO * (RHO_HI / RHO_LO).powf(i as f64 / (PITCHES - 1) as f64);
+ let bin = wav.at_rho(rho);
+ let wts = bin.weights();
+ let half = (bin.len_folded() - 1) as f64;
+
+ let mut readings = Vec::with_capacity(PHASES * HOPS);
+ for q in 0..PHASES {
+ let p = offset(q);
+ // sinc(k − p)
+ let x = move |k: isize| {
+ let d = PI * (k as f64 - p);
+ d.sin() / d
+ };
+ for m in hops(half, HOPS) {
+ let (e, c) = moments(&wts, &x, m);
+ if e > 0.0 {
+ // ρ |m + c/e − p|
+ readings.push((e, rho * (m as f64 + c / e - p).abs()));
+ }
+ }
+ }
+ (rho, bin.len_unfolded(), vec![readings])
+ })
+ .collect();
+
+ let [median, worst] = transport_report(
+ &format!("IMPULSE T_HAT (Q {Q}, γ {GAMMA}, quantum {QUANTUM}, tail {TAIL_DB:.0} dB)"),
+ &["impulse"],
+ &rows,
+ [MEDIAN_DB, WORST_DB],
+ );
+
+ assert!(
+ median < MEDIAN_DB,
+ "median row E·d {median:.2} dB re one period"
+ );
+ assert!(
+ worst < WORST_DB,
+ "worst row E·d {worst:.2} dB re one period"
+ );
+ }
+
+ /// Energy that time reassignment moves off a stationary tone, and how far, per detune.
+ ///
+ /// E·d = Σ E ρ |t̂ − m| / Σ E
+ ///
+ /// A stationary tone belongs to every hop, so truth is the hop itself. Error comes from the
+ /// image beating against the signal, which differs above and below the carrier.
+ #[test]
+ fn t_hat_tone_transport() {
+ const Q: f64 = 3.5;
+ const GAMMA: f64 = 3.0;
+ const QUANTUM: usize = 4;
+ const TAIL_DB: f64 = -40.0;
+
+ const PITCHES: usize = 48;
+ const RHO_LO: f64 = 0.01;
+ const RHO_HI: f64 = 0.375;
+ const DETUNES_C: [f64; 5] = [-300.0, -150.0, 0.0, 150.0, 300.0];
+ const PHASES: usize = 12;
+
+ const MEDIAN_DB: f64 = -30.0;
+ const WORST_DB: f64 = -20.0;
+
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(Q, GAMMA))
+ .max_load_quantum(QUANTUM)
+ .max_truncation(TAIL_DB)
+ .bake();
+
+ let rows: Vec<_> = (0..PITCHES)
+ .map(|i| {
+ // ρ_lo (ρ_hi / ρ_lo)^(i / (n − 1))
+ let rho = RHO_LO * (RHO_HI / RHO_LO).powf(i as f64 / (PITCHES - 1) as f64);
+ let bin = wav.at_rho(rho);
+ let wts = bin.weights();
+ let w0 = bin.velocity();
+
+ let families = DETUNES_C
+ .iter()
+ .map(|cents| {
+ // ω₀ 2^(c/1200)
+ let w = w0 * (cents / 1200.0).exp2();
+ (0..PHASES)
+ .map(|q| {
+ let theta = TAU * q as f64 / PHASES as f64;
+ let x = move |k: isize| (w * k as f64 + theta).cos();
+ let (e, c) = moments(&wts, &x, 0);
+ // ρ |c/e|
+ (e, rho * (c / e).abs())
+ })
+ .collect()
+ })
+ .collect();
+ (rho, bin.len_unfolded(), families)
+ })
+ .collect();
+
+ let names = DETUNES_C.map(|c| format!("{c:+.0}c"));
+ let names: Vec<&str> = names.iter().map(String::as_str).collect();
+
+ let [median, worst] = transport_report(
+ &format!("TONE T_HAT (Q {Q}, γ {GAMMA}, quantum {QUANTUM}, tail {TAIL_DB:.0} dB)"),
+ &names,
+ &rows,
+ [MEDIAN_DB, WORST_DB],
+ );
+
+ assert!(
+ median < MEDIAN_DB,
+ "median row E·d {median:.2} dB re one period"
+ );
+ assert!(
+ worst < WORST_DB,
+ "worst row E·d {worst:.2} dB re one period"
+ );
+ }
+
+ /// Energy that time reassignment moves off a Gaussian burst's center, and how far, per width.
+ ///
+ /// ĉ = Σ E t̂ / Σ E
+ /// E·d = Σ E_b ρ |ĉ − p| / Σ E_b
+ ///
+ /// Reassignment squeezes a burst toward its center by design, so each burst is one reading,
+ /// its total reported energy E_b at the displacement of its centroid.
+ #[test]
+ fn t_hat_burst_transport() {
+ const Q: f64 = 3.5;
+ const GAMMA: f64 = 3.0;
+ const QUANTUM: usize = 4;
+ const TAIL_DB: f64 = -40.0;
+
+ const PITCHES: usize = 48;
+ const RHO_LO: f64 = 0.01;
+ const RHO_HI: f64 = 0.375;
+ const HOPS: usize = 64;
+ const PHASES: usize = 6;
+ /// Burst widths, envelope σ.
+ const WIDTHS: [f64; 3] = [0.25, 0.75, 2.0];
+ const DETUNES_C: [f64; 3] = [-300.0, 0.0, 300.0];
+
+ const MEDIAN_DB: f64 = -20.0;
+ const WORST_DB: f64 = -10.0;
+
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(Q, GAMMA))
+ .max_load_quantum(QUANTUM)
+ .max_truncation(TAIL_DB)
+ .bake();
+
+ let rows: Vec<_> = (0..PITCHES)
+ .map(|i| {
+ // ρ_lo (ρ_hi / ρ_lo)^(i / (n − 1))
+ let rho = RHO_LO * (RHO_HI / RHO_LO).powf(i as f64 / (PITCHES - 1) as f64);
+ let bin = wav.at_rho(rho);
+ let wts = bin.weights();
+ let w0 = bin.velocity();
+ let half = (bin.len_folded() - 1) as f64;
+ // P / 2πρ
+ let sigma = wav.shape().p() / (TAU * rho);
+
+ let families = WIDTHS
+ .iter()
+ .map(|scale| {
+ let sd = (scale * sigma).max(1.0);
+ let mut readings = Vec::with_capacity(DETUNES_C.len() * PHASES);
+ for cents in DETUNES_C {
+ let w = w0 * (cents / 1200.0).exp2();
+ for q in 0..PHASES {
+ let (theta, p) = (TAU * q as f64 / PHASES as f64, offset(q));
+ // e^{−z²/2} cos(ω(k − p) + θ), z = (k − p) / sd
+ let x = move |k: isize| {
+ let t = k as f64 - p;
+ let z = t / sd;
+ (-0.5 * z * z).exp() * (w * t + theta).cos()
+ };
+ // (Σ E, Σ E t̂), E t̂ = E m + c
+ let (e, et) =
+ hops(half + 3.0 * sd, HOPS).fold((0.0, 0.0), |(e, et), m| {
+ let (em, c) = moments(&wts, &x, m);
+ (e + em, et + em * m as f64 + c)
+ });
+ // ρ |ĉ − p|
+ readings.push((e, rho * (et / e - p).abs()));
+ }
+ }
+ readings
+ })
+ .collect();
+ (rho, bin.len_unfolded(), families)
+ })
+ .collect();
+
+ let names = WIDTHS.map(|w| format!("b {w}σ"));
+ let names: Vec<&str> = names.iter().map(String::as_str).collect();
+
+ let [median, worst] = transport_report(
+ &format!("BURST T_HAT (Q {Q}, γ {GAMMA}, quantum {QUANTUM}, tail {TAIL_DB:.0} dB)"),
+ &names,
+ &rows,
+ [MEDIAN_DB, WORST_DB],
+ );
+
+ assert!(
+ median < MEDIAN_DB,
+ "median row E·d {median:.2} dB re one period"
+ );
+ assert!(
+ worst < WORST_DB,
+ "worst row E·d {worst:.2} dB re one period"
+ );
+ }
+
+ /// Energy time reassignment moves off a step's edge, and how far, for the default filter over
+ /// γ × Q × tail.
+ ///
+ /// E·d = Σ E ρ |t̂ − p| / Σ E
+ ///
+ /// Far from the edge the step is DC, so Ψ settles to ½M₀ and each leaked reading lands displaced
+ /// by its distance to the edge. The step's 1/ω spectrum weights the low skirt.
+ #[test]
+ fn t_hat_step_transport() {
+ const HOPS: usize = 96;
+ const PHASES: usize = 6;
+ /// Hop reach in half-spans, past where the edge leaves the window.
+ const REACH: f64 = 3.0;
+ /// Edge width, samples.
+ const EDGE: f64 = 0.5;
+
+ // (γ, Q, tail, [median row, worst row])
+ let mut summary = Vec::new();
+
+ for gamma in PITCH_GAMMAS {
+ for q in PITCH_QS {
+ for tail in PITCH_TAILS {
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(q, gamma))
+ .max_load_quantum(PITCH_QUANTUM)
+ .max_truncation(tail)
+ .bake();
+
+ let rows: Vec<_> = PITCH_RHOS
+ .into_iter()
+ .map(|rho| {
+ let bin = wav.at_rho(rho);
+ let wts = bin.weights();
+ let half = (bin.len_folded() - 1) as f64;
+
+ let mut readings = Vec::with_capacity(PHASES * HOPS);
+ for j in 0..PHASES {
+ let p = offset(j);
+ // ½ tanh((k − p) / w)
+ let x = move |k: isize| 0.5 * ((k as f64 - p) / EDGE).tanh();
+ for m in hops(REACH * half, HOPS) {
+ let (e, c) = moments(&wts, &x, m);
+ if e > 0.0 {
+ // ρ |m + c/e − p|
+ readings.push((e, rho * (m as f64 + c / e - p).abs()));
+ }
+ }
+ }
+ (rho, bin.len_unfolded(), vec![readings])
+ })
+ .collect();
+
+ let measured = transport_report(
+ &format!(
+ "STEP T_HAT (Q {q}, γ {gamma}, quantum {PITCH_QUANTUM}, \
+ tail {tail:.0} dB)"
+ ),
+ &["step"],
+ &rows,
+ [0.0, 0.0],
+ );
+ summary.push((gamma, q, tail, measured));
+ }
+ }
+ }
+
+ let tails = PITCH_TAILS.len();
+ let rule = "=".repeat(14 + 18 * tails);
+ let header = |lead: &str| {
+ print!(" {lead}");
+ for tail in PITCH_TAILS {
+ print!(" {:>17}", format!("{tail:.0} dB"));
+ }
+ println!();
+ };
+
+ // Worst over γ × Q per tail
+ let worst: Vec<[f64; 2]> = (0..tails)
+ .map(|t| {
+ summary
+ .iter()
+ .skip(t)
+ .step_by(tails)
+ .fold([f64::NEG_INFINITY; 2], |w, r| {
+ [w[0].max(r.3[0]), w[1].max(r.3[1])]
+ })
+ })
+ .collect();
+
+ println!("\n {rule}");
+ println!(" STEP T_HAT worst over γ × Q, E·d dB re one period");
+ println!(" {rule}");
+ header(&format!("{:>12}", ""));
+ for (label, i) in [("median row", 0), ("worst row", 1)] {
+ print!(" {label:>12}");
+ for w in &worst {
+ print!(" {:>17.2}", w[i]);
+ }
+ println!();
+ }
+ println!(" {rule}");
+
+ // Median and worst row E·d by tail, one row per γ × Q
+ println!("\n {rule}");
+ println!(" STEP T_HAT E·d dB re one period by tail, median / worst row");
+ println!(" {rule}");
+ header(&format!("{:>4} {:>5} ", "γ", "Q"));
+ for row in summary.chunks(tails) {
+ print!(" {:>4.1} {:>5.1} ", row[0].0, row[0].1);
+ for s in row {
+ print!(" {:>17}", format!("{:.2} / {:.2}", s.3[0], s.3[1]));
+ }
+ println!();
+ }
+ println!(" {rule}");
+ }
+
+ // Pitch transport
+
+ /// 1200 log2(1 + 1/600)
+ const PITCH_RES_C: f64 = 2.883;
+ /// Share of a filter's energy misplaced before the filter is unusable.
+ const PITCH_FAIL: f64 = 0.5;
+ /// Share of log ρ held by unusable filters before the wavelet is.
+ const WAVELET_FAIL: f64 = 0.1;
+
+ const PITCH_GAMMAS: [f64; 2] = [3.0, 4.0];
+ const PITCH_QS: [f64; 2] = [3.5, 12.5];
+ const PITCH_TAILS: [f64; 3] = [-40.0, -60.0, -80.0];
+ const PITCH_QUANTUM: usize = 4;
+
+ /// Sampled centers, denser where the top of the band degrades.
+ const PITCH_RHOS: [f64; 7] = [0.01, 0.03, 0.1, 0.2, 0.28, 0.33, 0.375];
+
+ /// Detunes in half-power half-widths.
+ const PITCH_DETUNES: [f64; 5] = [-1.0, -0.5, 0.0, 0.5, 1.0];
+
+ /// 1200 log2(1 + 1/2Q)
+ fn half_width_c(q: f64) -> f64 {
+ 1200.0 * (1.0 + 0.5 / q).log2()
+ }
+
+ /// Share of the log ρ span each center stands for, cells split at geometric midpoints.
+ fn rho_weights() -> [f64; PITCH_RHOS.len()] {
+ let l = PITCH_RHOS.map(f64::ln);
+ let last = l.len() - 1;
+ core::array::from_fn(|i| {
+ let lo = if i == 0 {
+ l[0]
+ } else {
+ 0.5 * (l[i - 1] + l[i])
+ };
+ let hi = if i == last {
+ l[last]
+ } else {
+ 0.5 * (l[i] + l[i + 1])
+ };
+ (hi - lo) / (l[last] - l[0])
+ })
+ }
+
+ /// (|Ψ|², ω₀ Re(D/Ψ), m + Re(T/Ψ))
+ fn reassign(wts: &Weights, x: &dyn Fn(isize) -> f64, m: isize, w0: f64) -> (f64, f64, f64) {
+ let [psi, dee, tee] = wts.project(x, m);
+ (
+ psi.norm_sqr(),
+ w0 * (dee / psi).re,
+ m as f64 + (tee / psi).re,
+ )
+ }
+
+ /// min(|1200 log2(ω̂/ω)|, 1200)
+ fn miss_c(w_hat: f64, w: f64) -> f64 {
+ (1200.0 * (w_hat / w).log2()).abs().min(1200.0)
+ }
+
+ /// 10 log10 u, dash where nothing was measured
+ fn db_cell(u: f64, width: usize) -> String {
+ if u > 0.0 {
+ format!("{:>width$.2}", 10.0 * u.log10())
+ } else {
+ format!("{:>width$}", "—")
+ }
+ }
+
+ /// Prints one IQM and failed share against their limits, returning whether both hold.
+ fn pitch_headline(label: &str, iqm_db: f64, share: f64, iqm_limit: f64) -> bool {
+ let verdict = |h: f64| if h >= 0.0 { "pass" } else { "FAIL" };
+ let (h_iqm, h_share) = (iqm_limit - iqm_db, WAVELET_FAIL - share);
+ let rule = "=".repeat(33);
+
+ println!("\n {rule}");
+ println!(" {label}");
+ println!(" {rule}");
+ println!(" {:>9} {:>10} {:>10}", "", "IQM dB", "failed");
+ println!(" {:>9} {iqm_db:>10.2} {:>9.1}%", "measured", 100.0 * share);
+ println!(
+ " {:>9} {iqm_limit:>10.2} {:>9.1}%",
+ "limit",
+ 100.0 * WAVELET_FAIL
+ );
+ println!(
+ " {:>9} {h_iqm:>10.2} {:>9.1}%",
+ "headroom",
+ 100.0 * h_share
+ );
+ println!(
+ " {:>9} {:>10} {:>10}",
+ "",
+ verdict(h_iqm),
+ verdict(h_share)
+ );
+ println!(" {rule}");
+
+ h_iqm >= 0.0 && h_share >= 0.0
+ }
+
+ /// Pitch transport over Q × γ × tail × ρ. `readings` returns one family of
+ /// (E, e, e_phys) per column in `names`, e measured from the physical model's truth and
+ /// e_phys the model's own departure from the carrier, both in cents.
+ ///
+ /// E·d = Σ E e/res / Σ E
+ /// miss = Σ E [e > res] / Σ E
+ /// IQM = E·d over the middle two quartiles of surviving filters
+ fn pitch_matrix(
+ title: &str,
+ names: &[String],
+ iqm_limits: [f64; PITCH_TAILS.len()],
+ readings: impl Fn(Bin<'_>, f64) -> Vec>,
+ ) {
+ // Σ E v / Σ E
+ let mean = |r: &[(f64, f64, f64)], v: &dyn Fn(&(f64, f64, f64)) -> f64| {
+ let (num, e) = r
+ .iter()
+ .fold((0.0, 0.0), |(n, e), x| (n + x.0 * v(x), e + x.0));
+ num / e
+ };
+ let ed = |r: &[(f64, f64, f64)]| mean(r, &|x| x.1 / PITCH_RES_C);
+ let phys = |r: &[(f64, f64, f64)]| mean(r, &|x| x.2 / PITCH_RES_C);
+ let miss = |r: &[(f64, f64, f64)]| mean(r, &|x| (x.1 > PITCH_RES_C) as u8 as f64);
+ let db = |u: f64| {
+ if u > 0.0 {
+ 10.0 * u.log10()
+ } else {
+ f64::INFINITY
+ }
+ };
+
+ let weights = rho_weights();
+ // (γ, Q, tail, IQM dB, failed share, [q1, q2, q3], phys median)
+ let mut summary = Vec::new();
+ let mut failures = Vec::new();
+
+ for gamma in PITCH_GAMMAS {
+ for q in PITCH_QS {
+ for (t, tail) in PITCH_TAILS.into_iter().enumerate() {
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(q, gamma))
+ .max_load_quantum(PITCH_QUANTUM)
+ .max_truncation(tail)
+ .bake();
+
+ // (ρ, w, taps, per family E·d, pooled readings)
+ let rows: Vec<_> = PITCH_RHOS
+ .into_iter()
+ .zip(weights)
+ .map(|(rho, w)| {
+ let bin = wav.at_rho(rho);
+ let families = readings(bin, q);
+ let per: Vec = families.iter().map(|f| ed(f)).collect();
+ let pooled: Vec<(f64, f64, f64)> = families
+ .iter()
+ .flat_map(|f| {
+ let total: f64 = f.iter().map(|v| v.0).sum();
+ f.iter().map(move |&(e, c, p)| (e / total, c, p))
+ })
+ .collect();
+ (rho, w, bin.len_unfolded(), per, pooled)
+ })
+ .collect();
+ let has_phys = rows.iter().any(|r| r.4.iter().any(|v| v.2 > 0.0));
+
+ println!(
+ "\n=== {title} (Q {q}, γ {gamma}, quantum {PITCH_QUANTUM}, \
+ tail {tail:.0} dB, res {PITCH_RES_C}c) ==="
+ );
+ println!(" E·d in dB re one resolution per family and pooled");
+ if has_phys {
+ println!(" phys is the model's own pull, excluded from E·d");
+ }
+ println!(" miss is E beyond res, q50 and q99 are e in cents\n");
+ print!(" {:>7} {:>5}", "rho", "taps");
+ for n in names {
+ print!(" {n:>8}");
+ }
+ print!(" {:>8}", "pooled");
+ if has_phys {
+ print!(" {:>8}", "phys");
+ }
+ println!(" {:>7} {:>8} {:>8}", "miss", "q50 c", "q99 c");
+
+ // (w, E·d, phys, failed)
+ let mut stats = Vec::with_capacity(rows.len());
+ for (rho, w, taps, per, pooled) in &rows {
+ let (row_ed, row_phys, row_miss) = (ed(pooled), phys(pooled), miss(pooled));
+ let failed = row_miss > PITCH_FAIL;
+ let mut spread: Vec<(f64, f64)> =
+ pooled.iter().map(|&(e, c, _)| (e, c)).collect();
+
+ print!(" {rho:>7.4} {taps:>5}");
+ for f in per {
+ print!(" {}", db_cell(*f, 8));
+ }
+ print!(" {}", db_cell(row_ed, 8));
+ if has_phys {
+ print!(" {}", db_cell(row_phys, 8));
+ }
+ println!(
+ " {:>6.2}% {:>8.3} {:>8.3} {}",
+ 100.0 * row_miss,
+ weighted_quantile(&mut spread, 0.5),
+ weighted_quantile(&mut spread, 0.99),
+ if failed { "FAIL" } else { "" }
+ );
+ stats.push((*w, row_ed, row_phys, failed));
+ }
+
+ // Survivors, weighted by log ρ share
+ let share = stats.iter().filter(|r| r.3).fold(0.0, |s, r| s + r.0);
+ let mut eds: Vec<(f64, f64)> =
+ stats.iter().filter(|r| !r.3).map(|r| (r.0, r.1)).collect();
+ let quartiles = if eds.is_empty() {
+ [f64::NAN; 3]
+ } else {
+ [0.25, 0.5, 0.75].map(|f| weighted_quantile(&mut eds, f))
+ };
+ // Σ w E·d / Σ w over q1 ≤ E·d ≤ q3
+ let (num, den) = eds
+ .iter()
+ .filter(|r| r.1 >= quartiles[0] && r.1 <= quartiles[2])
+ .fold((0.0, 0.0), |(n, d), r| (n + r.0 * r.1, d + r.0));
+ let iqm = db(num / den);
+ let mut physs: Vec<(f64, f64)> = stats.iter().map(|r| (r.0, r.2)).collect();
+ let phys_med = weighted_quantile(&mut physs, 0.5);
+
+ println!(
+ "\n E·d quartiles over survivors q1 {} median {} q3 {}",
+ db_cell(quartiles[0], 0),
+ db_cell(quartiles[1], 0),
+ db_cell(quartiles[2], 0),
+ );
+ let label = format!("Q {q} γ {gamma} tail {tail:.0}");
+ if !pitch_headline(&label, iqm, share, iqm_limits[t]) {
+ failures.push(label);
+ }
+ summary.push((gamma, q, tail, iqm, share, quartiles, phys_med));
+ }
+ }
+ }
+
+ // IQM by tail, one row per γ × Q
+ // Worst over γ × Q per tail
+ let tails = PITCH_TAILS.len();
+ let rule = "=".repeat(14 + 16 * tails);
+ let worst: Vec<(f64, f64)> = (0..tails)
+ .map(|t| {
+ summary
+ .iter()
+ .skip(t)
+ .step_by(tails)
+ .fold((f64::NEG_INFINITY, 0.0f64), |(i, s), r| {
+ (i.max(r.3), s.max(r.4))
+ })
+ })
+ .collect();
+ let verdict = |h: f64| if h >= 0.0 { "pass" } else { "FAIL" };
+ let header = |lead: &str| {
+ print!(" {lead:>12}");
+ for tail in PITCH_TAILS {
+ print!(" {:>15}", format!("{tail:.0} dB"));
+ }
+ println!();
+ };
+ let line = |label: &str, cell: &dyn Fn(usize) -> String| {
+ print!(" {label:>12}");
+ for t in 0..tails {
+ print!(" {:>15}", cell(t));
+ }
+ println!();
+ };
+
+ println!("\n {rule}");
+ println!(" {title} worst over γ × Q");
+ println!(" {rule}");
+ header("");
+ line("limit", &|t| format!("{:.2}", iqm_limits[t]));
+ line("headroom", &|t| {
+ format!("{:.2}", iqm_limits[t] - worst[t].0)
+ });
+ line("verdict", &|t| {
+ let h = (iqm_limits[t] - worst[t].0).min(WAVELET_FAIL - worst[t].1);
+ verdict(h).to_string()
+ });
+ println!(" {rule}");
+
+ // IQM by tail, one row per γ × Q
+ println!("\n {rule}");
+ println!(" {title} IQM dB re {PITCH_RES_C}c by tail, failed share where nonzero");
+ println!(" {rule}");
+ print!(" {:>4} {:>5} ", "γ", "Q");
+ for tail in PITCH_TAILS {
+ print!(" {:>15}", format!("{tail:.0} dB"));
+ }
+ println!();
+ for row in summary.chunks(tails) {
+ print!(" {:>4.1} {:>5.1} ", row[0].0, row[0].1);
+ for s in row {
+ let cell = match s.4 > 0.0 {
+ true => format!("{:.2} ({:.0}%)", s.3, 100.0 * s.4),
+ false => format!("{:.2}", s.3),
+ };
+ print!(" {cell:>15}");
+ }
+ println!();
+ }
+ println!(" {rule}");
+
+ assert!(
+ failures.is_empty(),
+ "{title} failed wavelets: {}",
+ failures.join(", ")
+ );
+ }
+
+ /// Pitch misplaced off a stationary tone across the band a filter answers for.
+ ///
+ /// e = 1200 log2(ω̂ / ω)
+ #[test]
+ fn r_hat_tone_transport() {
+ const PHASES: usize = 12;
+ // Empirical. Keep updated. Maps to the truncation dB.
+ const IQM_DB: [f64; 3] = [-12.0, -18.0, -29.0];
+
+ let names = PITCH_DETUNES.map(|s| format!("{s:+.1}h"));
+ pitch_matrix("TONE R_HAT", &names, IQM_DB, |bin, q| {
+ let (wts, w0) = (bin.weights(), bin.velocity());
+ PITCH_DETUNES
+ .iter()
+ .map(|s| {
+ // ω₀ 2^(s h / 1200)
+ let w = w0 * (s * half_width_c(q) / 1200.0).exp2();
+ (0..PHASES)
+ .map(|p| {
+ let theta = TAU * p as f64 / PHASES as f64;
+ let x = move |k: isize| (w * k as f64 + theta).cos();
+ let (e, w_hat, _) = reassign(&wts, &x, 0, w0);
+ (e, miss_c(w_hat, w), 0.0)
+ })
+ .collect()
+ })
+ .collect()
+ });
+ }
+
+ /// Pitch misplaced off a linear chirp, read at its reassigned time.
+ ///
+ /// e = 1200 log2(ω̂ / (ω₀ + a t̂))
+ ///
+ /// Rates are c = a σ², σ² the envelope variance in samples.
+ #[test]
+ fn r_hat_chirp_transport() {
+ const RATES: [f64; 3] = [0.05, 0.2, 0.5];
+ const READINGS: usize = 32;
+ const PHASES: usize = 6;
+ const IQM_DB: [f64; 3] = [-5.0, -15.0, -25.0];
+
+ let names = RATES.map(|c| format!("aσ² {c}"));
+ pitch_matrix("CHIRP R_HAT", &names, IQM_DB, |bin, q| {
+ let (wts, w0) = (bin.weights(), bin.velocity());
+ let var = wts.psi().envelope_var();
+ let span = half_width_c(q);
+ RATES
+ .iter()
+ .map(|c| {
+ let a = c / var;
+ let mut r = Vec::with_capacity(READINGS * PHASES);
+ for j in 0..READINGS {
+ // ω₀ 2^(δ/1200) = ω₀ + a m
+ let detune = span * (2.0 * j as f64 / (READINGS - 1) as f64 - 1.0);
+ let m = (w0 * ((detune / 1200.0).exp2() - 1.0) / a).round() as isize;
+ for p in 0..PHASES {
+ let theta = TAU * p as f64 / PHASES as f64;
+ // φ(k) = ω₀k + ½ak² + θ
+ let x = move |k: isize| {
+ let k = k as f64;
+ (w0 * k + 0.5 * a * k * k + theta).cos()
+ };
+ let (e, w_hat, t_hat) = reassign(&wts, &x, m, w0);
+ r.push((e, miss_c(w_hat, w0 + a * t_hat), 0.0));
+ }
+ }
+ r
+ })
+ .collect()
+ });
+ }
+
+ /// Pitch misplaced off Gaussian bursts at every hop they reach, measured from the product
+ /// centroid a Gaussian envelope pair would reassign to.
+ ///
+ /// ω* = (ω σ_x² + ω₀ σ_ψ²) / (σ_x² + σ_ψ²)
+ /// e = 1200 log2(ω̂ / ω*)
+ /// e_phys = 1200 log2(ω* / ω)
+ #[test]
+ fn r_hat_burst_transport() {
+ /// Burst widths, filter envelope σ.
+ const WIDTHS: [f64; 3] = [1.0, 2.0, 4.0];
+ const HOPS: usize = 32;
+ const PHASES: usize = 4;
+ // XXX Would set limits here, but the "worst" is always a Q = 3.5 row that is probably just
+ // barely big enough to locate the burst. With some more effort I'm sure something will
+ // become apparent.
+ const IQM_DB: [f64; 3] = [0.0; 3];
+
+ let names = WIDTHS.map(|w| format!("b {w}σ"));
+ pitch_matrix("BURST R_HAT", &names, IQM_DB, |bin, q| {
+ let (wts, w0) = (bin.weights(), bin.velocity());
+ let half = (bin.len_folded() - 1) as f64;
+ let var = wts.psi().envelope_var();
+ WIDTHS
+ .iter()
+ .map(|scale| {
+ let sd = (scale * var.sqrt()).max(1.0);
+ let sd2 = sd * sd;
+ let mut r = Vec::new();
+ for s in PITCH_DETUNES {
+ let w = w0 * (s * half_width_c(q) / 1200.0).exp2();
+ // ω*
+ let w_model = (w * sd2 + w0 * var) / (sd2 + var);
+ let phys = miss_c(w_model, w);
+ for j in 0..PHASES {
+ let (theta, p) = (TAU * j as f64 / PHASES as f64, offset(j));
+ // e^{−z²/2} cos(ω(k − p) + θ), z = (k − p) / sd
+ let x = move |k: isize| {
+ let t = k as f64 - p;
+ let z = t / sd;
+ (-0.5 * z * z).exp() * (w * t + theta).cos()
+ };
+ for m in hops(half + 3.0 * sd, HOPS) {
+ let (e, w_hat, _) = reassign(&wts, &x, m, w0);
+ r.push((e, miss_c(w_hat, w_model), phys));
+ }
+ }
+ }
+ r
+ })
+ .collect()
+ });
+ }
+
+ /// Bank reading of a tone by dilation, centroid and spread in cents.
+ ///
+ /// ```text
+ /// B = ∫ H·(H_d/r − H) dδ / ∫ H² dδ
+ /// S² = ∫ (H_d/r − H)² dδ / ∫ H² dδ − B²
+ /// ```
+ fn confluence(psi: Fold<'_>, d: Fold<'_>, w0: f64, octaves: f64, n: usize) -> (f64, f64) {
+ let span = octaves * LN_2;
+ let (mut e, mut eb, mut ebb) = (0.0, 0.0, 0.0);
+ for i in 0..n {
+ let delta = span * (2.0 * i as f64 / (n - 1) as f64 - 1.0);
+ let r = delta.exp();
+ if w0 * r >= PI {
+ continue;
+ }
+ let (h, hd) = (psi.dtft(w0 * r), d.dtft(w0 * r));
+ // H_d/r − H
+ let res = hd / r - h;
+ e += h * h;
+ eb += h * res;
+ ebb += res * res;
+ }
+ let b = eb / e;
+ let cents = 1200.0 / LN_2;
+ (cents * b, cents * (ebb / e - b * b).max(0.0).sqrt())
+ }
+
+ /// Ridge offset and width across γ at fixed Q, against the predicted log centroid.
+ #[test]
+ fn confluence_vs_gamma() {
+ const QS: [f64; 3] = [3.5, 5.0, 8.5];
+ const GAMMAS: [f64; 4] = [1.0, 2.0, 3.0, 4.0];
+ const RHOS: [f64; 4] = [0.1, 0.2, 0.25, 0.33];
+ const TAIL_DB: f64 = -60.0;
+ const OCTAVES: f64 = 3.0;
+ const SAMPLES: usize = 2049;
+
+ println!("\n=== CONFLUENCE vs GAMMA (tail {TAIL_DB:.0} dB) ===");
+ println!(
+ " {:>5} {:>4} {:>6} {:>9} {:>9} {:>9} {:>7}",
+ "Q", "γ", "rho", "E[δ] c", "B c", "S c", "κ̂"
+ );
+
+ for q in QS {
+ for gamma in GAMMAS {
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(q, gamma))
+ .max_truncation(TAIL_DB)
+ .bake();
+ let p = wav.shape().p();
+ // −γ/(4P²)
+ let centroid = -1200.0 / LN_2 * gamma / (4.0 * p * p);
+
+ for rho in RHOS {
+ let bin = wav.at_rho(rho);
+ let wts = bin.weights();
+ let (b, s) = confluence(wts.psi(), wts.d(), bin.velocity(), OCTAVES, SAMPLES);
+ println!(
+ " {q:>5.1} {gamma:>4.1} {rho:>6.3} {centroid:>+9.2} {b:>+9.3} {s:>9.2} {:>+7.3}",
+ -b / centroid
+ );
+ }
+ println!();
+ }
+ }
+ }
+}
diff --git a/mutate-lib/src/dsp/wavelet/refine.rs b/mutate-lib/src/dsp/wavelet/refine.rs
new file mode 100644
index 00000000..6862de1d
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/refine.rs
@@ -0,0 +1,345 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # Refine
+//!
+//! Polish off the worst of the spectral and transient response artifacts from the imperfect
+//! restriction of the finite wavelet. Write the final weights to `f32` output in a precision and
+//! goal-aware manner.
+//!
+//! > If the state is captive to narrow interests, then why do you wait for the state to organize
+//! > what you claim to be an overwhelming mass of your own interests?
+//! >
+//! > - Major Edward Wuncler III, Halliburton War Veteran
+//!
+//! ⚠️ This module has been recently re-developed. Doc comments are design outputs, not
+//! necessarilly fully implemented.
+//!
+//! ## Motivation
+//!
+//! [`Restriction`](super::restrict) approximates an infinite ideal on a finite support. Finite
+//! support implies truncation. Taper has been found useful at controlling the damage of
+//! truncation. Spectrally aware tuning of taper application can enhance the overall filter
+//! performance while re-establishing characteristics where the virtues they guarantee are just as
+//! true for the finite FIR as they were for the infinite ideal wavelet.
+//!
+//! ## Proper Constraints
+//!
+//! The dilemma of designing the response with any spectral approach is that improper solver
+//! constraints can, for example, pursue an equiripple spectral response to pure tones that is
+//! nonetheless extremely fragile to transients, a result that will not perform well at all in
+//! practice. Physically, we can intuit that the pedestals and spiky filter shapes resulting from
+//! pure-tone optimization must generate unwanted, very non-smooth transient responses.
+//!
+//! A reasonable constraint envelope may begin with what dead reckoning solutions for tapering would
+//! take away. The [`Cylinder`](super::restrict::Taper::Cylinder) taper extracts mass equal to
+//! the `K + 1` tap across the entire support. If our deviations land between or not far from the
+//! region bracketed by native truncation and our taper, the shape is guaranteed to be quite
+//! Morse-like no matter what the solver does. If we consider distance from the Morse curvature as
+//! an extra element of cost, we can balance the intuitive transient robustness of the base Morse
+//! shape with further spectral tuning.
+//!
+//! The ideal Morse wavelet does **not** have a constant angular velocity but instead has a phase
+//! curvature that shapes the main lobe. This chirped carrier and its phase curvature show up as a
+//! degree of freedom when, in order to balance the moments, we move filter mass along the spiral,
+//! changing its phase. We may also twist the spiral faster or slower, changing the phase curvature
+//! and pushing mass around the axis. Both modifying the spiral and moving mass along the spiral
+//! change the filter's net angle and magnitude.
+//!
+//! ## Solver Goals
+//!
+//! > Optimal wavelet behavior is then found to be achieved by minimizing third central moments in
+//! > both the frequency and the time domains.
+//!
+//! — Lilly & Olhede, [*Higher-Order Properties of Analytic Wavelets*][lilly-olhede] (2009).
+//!
+//! Some refinements are aiming to restore analytically mandatory characteristics. Others are
+//! spectrally opportunistic and take advantage of the free real-estate afforded where truncation
+//! left no choice but to step into the non-analytic FIR optimization space. The final goals
+//! minimize changes and therefore prevent a walk too far from robust transient response inherent to
+//! the basic Morse shape.
+//!
+//! The first side lobes, main lobe width (especially the transition band), and noise floor shape
+//! may all have some low hanging fruit, features that can be directly tied to specific weights. If
+//! polishing these features away can be accomplished within the limited support and the limited
+//! freedom of truncation, that's a win.
+//!
+//! [lilly-olhede]: https://static.aminer.org/pdf/PDF/001/231/038/higher_order_properties_of_analytic_wavelets.pdf
+
+// NEXT Work on this module is yet missing one critical model. The performance of one filter is not
+// what creates a filter bank. If we had to rely on individual filters to create independent output
+// lanes, then every filter must be perfect. In a bank however, we only want high injectivity,
+// meaning every unique input maps to a unique output. It is not necessary to emit every possible
+// output (surjective), which is physically impossible due to destructive interference in the air
+// that carries the sound.
+//
+// What is known for now is that garbage out cannot become reconstructive input. For each input,
+// some outputs must lead to the correct identification of the input and each non-present input must
+// lead to some cancelling outputs that correctly identify the absence of that input. A lack of
+// anti-correlation in error, noise or confusion, is the property we want to minimize.
+//
+// Correspondingly, a filter that looks somewhat ugly in isolation might be exactly what the bank
+// needs. Until the bank's needs are better understood, "cleaning up" individual filters may yet go
+// in a wrong direction. Whatever direction it goes, it cannot be an informed direction.
+// Characterizing the bank's demands of filters must come first.
+// NOTE Solver direction is headed towards a combination of probes from the inspect module, analytic
+// conditions like the jet terms and moments creating a null space, and likely some probes against
+// reassignment problems.
+
+use core::f64::consts::{FRAC_PI_2, PI, TAU};
+
+use num_complex::Complex64;
+
+use super::Shape;
+
+/// Conditions restored after restriction.
+#[derive(Clone, Copy, Debug)]
+pub enum Refinement {
+ None,
+ /// Radial profiles on the spiral over its last `turns`, least norm, spent into the support comb.
+ ///
+ /// ```text
+ /// M_p = 0, p ∈ moments ∩ [0, β)
+ /// δH⁽ᵖ⁾(ω₀) = 0, p ∈ jet
+ /// ```
+ Reach {
+ moments: &'static [u32],
+ jet: &'static [u32],
+ turns: f64,
+ tangent: bool,
+ spare: usize,
+ },
+}
+
+impl Default for Refinement {
+ fn default() -> Self {
+ Self::Reach {
+ moments: &[0],
+ jet: &[0, 1, 2],
+ turns: 5.0,
+ tangent: true,
+ spare: 16,
+ }
+ }
+}
+
+impl Refinement {
+ pub(super) fn apply(self, psi: &mut [Complex64], shape: Shape, rho: f64) {
+ let Refinement::Reach {
+ moments,
+ jet,
+ turns,
+ tangent,
+ spare,
+ } = self
+ else {
+ return;
+ };
+ let len = psi.len();
+ let legal = shape.vanishing_moments();
+ let w0 = TAU * rho;
+
+ // M_p = 0
+ let mut rows: Vec<(Functional, f64)> = moments
+ .iter()
+ .copied()
+ .filter(|p| legal.contains(p))
+ .map(|p| (Functional::response(len, 0.0, p), 0.0))
+ .collect();
+ // H⁽ᵖ⁾(ω₀) held
+ rows.extend(jet.iter().map(|&p| {
+ let f = Functional::response(len, w0, p);
+ let held = f.eval(psi);
+ (f, held)
+ }));
+
+ frenet(
+ psi,
+ &Profiles::edge(len, turns / rho, rows.len() + 1 + spare),
+ tangent,
+ &rows,
+ );
+ }
+}
+
+/// Radial profiles along the spiral's Frenet frame.
+///
+/// ```text
+/// δ_k = Σ_j μ_j b_j(k) e_j(k), e ∈ {u_k, i u_k}, u_k = ψ_k / |ψ_k|
+/// G_ij = Σ_k Re(c̄_ik b_j(k) e_j(k))
+/// μ = Gᵀλ, G Gᵀ λ = t − Cψ
+/// ```
+pub(super) fn frenet(
+ psi: &mut [Complex64],
+ profiles: &Profiles,
+ tangent: bool,
+ rows: &[(Functional, f64)],
+) {
+ let unit: Vec = psi.iter().map(|p| p / p.norm()).collect();
+
+ // b_j(k) e_j(k)
+ let turns: &[Complex64] = match tangent {
+ true => &[Complex64::ONE, Complex64::I],
+ false => &[Complex64::ONE],
+ };
+
+ // Hermitian atoms, the center tap real
+ let atoms = profiles.0.iter().flat_map(|b| {
+ turns.iter().map(|t| {
+ let mut a: Vec = b.iter().zip(&unit).map(|(b, u)| b * t * u).collect();
+ a[0].im = 0.0;
+ a
+ })
+ });
+
+ // ⟨a, b⟩ = Σ_k m_k Re(ā_k b_k), m₀ = 1, m_k = 2
+ let inner = |a: &[Complex64], b: &[Complex64]| -> f64 {
+ a.iter()
+ .zip(b)
+ .enumerate()
+ .map(|(k, (a, b))| if k == 0 { 1.0 } else { 2.0 } * (a.conj() * b).re)
+ .sum()
+ };
+
+ // orthonormal span, least ‖δ‖ under min ‖μ‖
+ let mut basis: Vec> = Vec::new();
+ for mut a in atoms {
+ let before = inner(&a, &a).sqrt();
+ for _ in 0..2 {
+ for e in &basis {
+ let c = inner(e, &a);
+ for (x, y) in a.iter_mut().zip(e) {
+ *x -= c * y;
+ }
+ }
+ }
+ let norm = inner(&a, &a).sqrt();
+ if norm > 1e-10 * before {
+ a.iter_mut().for_each(|x| *x /= norm);
+ basis.push(a);
+ }
+ }
+ let atoms = basis;
+
+ let g: Vec> = rows
+ .iter()
+ .map(|(r, _)| {
+ atoms
+ .iter()
+ .map(|a| {
+ r.0.iter()
+ .zip(a)
+ .map(|(c, a)| c.re * a.re + c.im * a.im)
+ .sum()
+ })
+ .collect()
+ })
+ .collect();
+
+ let n = rows.len();
+ let mut gram = vec![0.0; n * n];
+ for i in 0..n {
+ for j in 0..=i {
+ let v: f64 = g[i].iter().zip(&g[j]).map(|(a, b)| a * b).sum();
+ gram[i * n + j] = v;
+ gram[j * n + i] = v;
+ }
+ }
+
+ let mut lambda: Vec = rows.iter().map(|(r, t)| t - r.eval(psi)).collect();
+ cholesky(&mut gram, &mut lambda);
+
+ for (j, a) in atoms.iter().enumerate() {
+ let mu: f64 = g.iter().zip(&lambda).map(|(gi, l)| gi[j] * l).sum();
+ for (p, a) in psi.iter_mut().zip(a) {
+ *p += mu * a;
+ }
+ }
+}
+
+/// Real gain profiles over the reach, applied along each tap's own phase.
+///
+/// ```text
+/// δ_k = u_k Σ_j μ_j b_j(k), u_k = ψ_k / |ψ_k|
+/// ```
+pub(super) struct Profiles(Vec>);
+
+impl Profiles {
+ /// b_j(k) = sin²(πx/2) xʲ, x = clamp((k + 1 − K)/L + 1, 0, 1)
+ pub fn edge(len: usize, width: f64, order: usize) -> Self {
+ let axis = len as f64;
+ let x: Vec = (0..len)
+ .map(|k| ((k as f64 + 1.0 - axis) / width + 1.0).clamp(0.0, 1.0))
+ .collect();
+ Profiles(
+ (0..order as i32)
+ .map(|j| {
+ x.iter()
+ .map(|x| (FRAC_PI_2 * x).sin().powi(2) * x.powi(j))
+ .collect()
+ })
+ .collect(),
+ )
+ }
+}
+
+/// A real linear functional of folded Hermitian taps.
+///
+/// ```text
+/// L(ψ) = Σ_k Re(c̄_k ψ_k)
+/// ```
+pub(super) struct Functional(Vec);
+
+impl Functional {
+ /// H⁽ᵖ⁾(ω), c_k = 2 (ik)ᵖ e^{iωk}
+ pub fn response(len: usize, w: f64, p: u32) -> Self {
+ let mut c: Vec = (0..len)
+ .map(|k| {
+ let k = k as f64;
+ Complex64::new(0.0, k).powu(p) * Complex64::from_polar(2.0, w * k)
+ })
+ .collect();
+ // the center tap unfolds once
+ c[0] *= 0.5;
+ Functional(c)
+ }
+
+ pub fn eval(&self, psi: &[Complex64]) -> f64 {
+ self.0
+ .iter()
+ .zip(psi)
+ .map(|(c, p)| c.re * p.re + c.im * p.im)
+ .sum()
+ }
+}
+
+/// g x = r in place, g symmetric positive definite and row major.
+fn cholesky(g: &mut [f64], r: &mut [f64]) {
+ factor(g, r.len());
+ solve(g, r);
+}
+
+/// g = L Lᵀ, L in the lower triangle.
+fn factor(g: &mut [f64], n: usize) {
+ for j in 0..n {
+ let d = (g[j * n + j] - (0..j).map(|k| g[j * n + k].powi(2)).sum::()).sqrt();
+ g[j * n + j] = d;
+ for i in j + 1..n {
+ g[i * n + j] =
+ (g[i * n + j] - (0..j).map(|k| g[i * n + k] * g[j * n + k]).sum::()) / d;
+ }
+ }
+}
+
+/// L Lᵀ x = r in place.
+fn solve(g: &[f64], r: &mut [f64]) {
+ let n = r.len();
+ // L y = r
+ for i in 0..n {
+ r[i] = (r[i] - (0..i).map(|k| g[i * n + k] * r[k]).sum::()) / g[i * n + i];
+ }
+ // Lᵀ x = y
+ for i in (0..n).rev() {
+ r[i] = (r[i] - (i + 1..n).map(|k| g[k * n + i] * r[k]).sum::()) / g[i * n + i];
+ }
+}
diff --git a/mutate-lib/src/dsp/wavelet/restrict.rs b/mutate-lib/src/dsp/wavelet/restrict.rs
new file mode 100644
index 00000000..44885439
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/restrict.rs
@@ -0,0 +1,907 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # Restrict
+//!
+//! Squeeze the high-resolution mother wavelet grid into `N` taps.
+//!
+//! > Lab-grown beef is not technology. The real technology is *grinding* it. We are bringing to
+//! > the world the first product of it's kind. The narrow strings of beef are chopped, gathered by
+//! > real artisans into a flat, circular form, and finally smashed into smithereens.
+//! >
+//! > *applause*
+//! >
+//! > - Professor Arima Nayar, MSc in Mathematics
+//!
+//! Naively, we may sample the motherlet at the point nearest to `k`, and tell our boss that we have
+//! done the job.
+//!
+//! ## That is Not Good Enough
+//!
+//! At high omega, the motherlet is beginning to alias with N. Her smooth curves will become
+//! reduced to formless points, like pushing Michelangelo's David through a cheese grater.
+//!
+//! Instead, we want the result of the cheese grater to *look* the same to audio as the ideal
+//! wavelet. Since the audio has gone through roughly the same cheese grater, our job is made a
+//! little bit simpler. In the restriction step, we are mainly concerned with ensuring that the
+//! shape of the wavelet we will refine is maximally well preserved every time we shove it through
+//! the grater.
+
+use std::f64::consts::{FRAC_PI_2, PI, TAU};
+
+use num_complex::Complex64;
+
+use super::{generate::hermite, inspect::bisect, spec::Shape, Fold, Grid, PEAK_GAIN};
+
+/// Largest share of the center tap the knee may remove.
+const CENTER_SHARE: f64 = 0.5;
+/// Deepest cliff ringing an f32 table resolves. Every taper clamps above it.
+const F32_MIN_CLIFF_SCALE: f64 = 0.5 * f32::EPSILON as f64;
+/// Past this depth of the modeled edge re the crest, cells may ripple where the saddle and
+/// endpoint tails beat, and the envelope model sets the removal fractions.
+const ANALYTIC_DB: f64 = -200.0;
+
+/// How the motherlet lands on a cell. `Nearest` is technically correct in a sense, but `Axial`,
+/// **the default**, has been found to be more robust near edge cases. `Complex` sags in much the
+/// same places where `Nearest` sags. `Weighted` can sometimes outperform the others on image dB
+/// near higher `ω`, but it's not a great trade. `Weighted` also obtains consistent monotonic
+/// envelope decay in the far tail.
+#[derive(Clone, Copy, Default)]
+pub enum Quadrature {
+ /// ψ at the tap center.
+ ///
+ /// ```text
+ /// h_k = ψ(kρ)
+ /// ```
+ Nearest,
+ /// Cell mean of ψ.
+ ///
+ /// ```text
+ /// h_k = (1/ρ) ∫_{C_k} ψ du
+ /// ```
+ ///
+ /// The box is real and even about the cell, so the restriction commutes with input phase.
+ Complex,
+ /// Cell means of |ψ| and of the phase residual against the carrier, recombined.
+ ///
+ /// ```text
+ /// h_k = ā_k · e^{i(2πkρ + θ̄_k)}, θ = arg(ψ e^{-2πiu})
+ /// ```
+ ///
+ /// Nonlinear. Intra-cell rotation cannot cancel magnitude, so the crest keeps its height.
+ #[default]
+ Axial,
+ /// Trapezoidal footprint of width 3ρ over the cell means.
+ ///
+ /// ```text
+ /// h_k = (B_{k-1} + 2 B_k + B_{k+1}) / 4
+ /// ```
+ Weighted,
+}
+
+/// Since we're writing an infinite ideal wavelet to a finite support, we must truncate. Tapering
+/// can control some of the damage and leave us closer to an optimal solution without much work.
+///
+/// - `Rectangle` is noop, just truncate, leaving behind the cliff.
+/// - `Cylinder` subtracts a cylinder equal to the `K + 1` tap's magnitude, softening the cliff to
+/// just the rate of change at tap `K`.
+/// - `Knee`, the **default**, is axially aware like `Cylinder`, but uses a curve to modulate the taper into the final
+/// taps, leaving more of the center mass alone.
+#[derive(Clone, Copy)]
+pub enum Taper {
+ /// Full amplitude to the last tap.
+ Rectangle,
+ /// Remove the first discarded tap's magnitude from every other tap, subtracting a cylinder from
+ /// the middle. Gain correction will scale the resulting shape up, and the natural result has a
+ /// thinner tail, higher envelope slope to get back up to full gain, and a steeper shoulder
+ /// that restores some moment earlier.
+ ///
+ /// ```text
+ /// g_k = 1 − a_K / a_k
+ /// ```
+ ///
+ /// `a_K < a_k` over the reach, so `g_k` is a gain in (0, 1) and no tap can change sign.
+ Cylinder,
+ /// A profile through `a_K` with curvature `κ`. Like cylinder, but modulated by a curve flowing
+ /// into the edge.
+ ///
+ /// ```text
+ /// g_k = 1 − c_k / a_k, c_k = a_K (1 + (1 − (k/K)^n) / κ)
+ /// ```
+ Knee { curvature: f64 },
+}
+
+impl Default for Taper {
+ fn default() -> Self {
+ // The only use for Cylinder and Rectangle is basically to demonstrate that tapering is very
+ // important. Rectangle naturally leaves behind a Gibbs ringing floor.
+ Self::Knee { curvature: 0.35 }
+ }
+}
+
+#[derive(Clone, Copy, Default)]
+pub struct Restriction {
+ pub quadrature: Quadrature,
+ pub taper: Taper,
+ pub derivative: Derivative,
+}
+
+impl Restriction {
+ /// Writes `out.len()` folded weights, `out[0]` real.
+ pub(super) fn psi_into(self, grid: Grid, rho: f64, out: &mut [Complex64]) {
+ let reach = out.len();
+ let mut cells = vec![Complex64::default(); reach + 1];
+ self.quadrature.cells_into(grid, rho, &mut cells);
+
+ let gain = self.taper.gains(&cells, grid.shape, rho);
+ for (o, (c, g)) in out.iter_mut().zip(cells.iter().zip(gain)) {
+ *o = c * g;
+ }
+ out[0].im = 0.0;
+ }
+}
+
+impl Quadrature {
+ /// Cell values for `k` in `[0, out.len())`, the last being the first discarded.
+ fn cells_into(self, grid: Grid, rho: f64, out: &mut [Complex64]) {
+ let inv = rho.recip();
+
+ match self {
+ Quadrature::Nearest => {
+ for (j, o) in out.iter_mut().enumerate() {
+ *o = grid.at(j as f64 * rho);
+ }
+ }
+ Quadrature::Complex => {
+ // the center cell is symmetric about u = 0, so the odd parts cancel
+ out[0] = Complex64::new(2.0 * inv * grid.mass(0.0, 0.5 * rho).re, 0.0);
+ for (j, o) in out.iter_mut().enumerate().skip(1) {
+ *o = inv * grid.mass((j as f64 - 0.5) * rho, (j as f64 + 0.5) * rho);
+ }
+ }
+ Quadrature::Axial => {
+ let (a, da) = magnitude(grid);
+ let (t, dt) = residual(grid);
+ let mean = |p: &[f64], dp: &[f64], lo: f64, hi: f64| {
+ inv * hermite::integrate_1d(p, dp, lo, hi, grid.du)
+ };
+
+ out[0] = Complex64::new(2.0 * mean(&a, &da, 0.0, 0.5 * rho), 0.0);
+ for (j, o) in out.iter_mut().enumerate().skip(1) {
+ let (lo, hi) = ((j as f64 - 0.5) * rho, (j as f64 + 0.5) * rho);
+ let arg = TAU * j as f64 * rho + mean(&t, &dt, lo, hi);
+ let (s, c) = arg.sin_cos();
+ *o = mean(&a, &da, lo, hi) * Complex64::new(c, s);
+ }
+ }
+ Quadrature::Weighted => {
+ Quadrature::Complex.cells_into(grid, rho, out);
+
+ // B_{-1} = conj(B_1), and one cell past the reach to close the stencil
+ let past = inv
+ * grid.mass(
+ (out.len() as f64 - 0.5) * rho,
+ (out.len() as f64 + 0.5) * rho,
+ );
+ let at = |j: isize| match j {
+ -1 => out[1].conj(),
+ j if j as usize == out.len() => past,
+ j => out[j as usize],
+ };
+
+ const AXIS: [f64; 3] = [0.25, 0.5, 0.25];
+ let smooth: Vec = (0..out.len() as isize)
+ .map(|j| {
+ AXIS.iter()
+ .enumerate()
+ .map(|(i, &w)| w * at(j + i as isize - 1))
+ .sum()
+ })
+ .collect();
+ out.copy_from_slice(&smooth);
+ }
+ }
+ }
+}
+
+impl Taper {
+ /// One real gain per written tap, from the reach's first discarded magnitude.
+ fn gains(self, cells: &[Complex64], shape: Shape, rho: f64) -> Vec {
+ let reach = cells.len() - 1;
+ let axis = reach as f64;
+ let edge = cells[reach].norm();
+
+ // |H| ≤ a_0 + 2 Σ_{k≥1} a_k
+ let crest = 2.0 * cells[..reach].iter().map(|c| c.norm()).sum::() - cells[0].norm();
+ let floor = F32_MIN_CLIFF_SCALE * crest;
+
+ // ln(â_K/â_0), −K â'_K/â_K
+ let (ln_edge, s_edge) = shape.envelope(axis * rho);
+ let analytic = 20.0 * (cells[0].norm() * ln_edge.exp() / crest).log10() < ANALYTIC_DB;
+
+ // c_k / a_K
+ let lift: Box f64> = match self {
+ Taper::Rectangle => return vec![1.0; reach],
+ Taper::Cylinder => Box::new(|_| 1.0),
+ Taper::Knee { curvature } => {
+ let s = match analytic {
+ true => s_edge,
+ false => {
+ let s = -axis * (edge - cells[reach - 1].norm()) / edge;
+ if s < 0.0 {
+ eprintln!(
+ "reversed knee curvature {s:.3} at ρ {rho}, K {reach}, \
+ falling back to analytic"
+ );
+ s_edge
+ } else {
+ s
+ }
+ }
+ };
+ let n = curvature * s;
+ Box::new(move |j: f64| 1.0 + (1.0 - (j / axis).powf(n)) / curvature)
+ }
+ };
+
+ // r_k = c_k / a_k, the envelope standing in for the cells past ANALYTIC_DB
+ let share = |j: usize| match analytic {
+ true => lift(j as f64) * (ln_edge - shape.envelope(j as f64 * rho).0).exp(),
+ false => lift(j as f64) * edge / cells[j].norm(),
+ };
+
+ (0..reach)
+ .map(|j| soft_gain(1.0 - share(j), floor / cells[j].norm()))
+ .collect()
+ }
+
+ /// Envelope sigmas at the cut under which the profile overtakes the crest.
+ ///
+ /// ```text
+ /// c_0 = a_K (1 + 1/κ) < a_0, a_K / a_0 = e^{−x²/2}
+ /// x_min = √(2 ln(1 + 1/κ))
+ /// ```
+ pub(super) fn x_min(self) -> f64 {
+ match self {
+ Taper::Knee { curvature } => (2.0 * (1.0 + curvature.recip()).ln()).sqrt(),
+ Taper::Rectangle | Taper::Cylinder => 0.0,
+ }
+ }
+}
+
+/// `arg(ψ e^{-2πiu})` unwrapped, and its derivative. `φ' = 2π Re(conj(ψ)·d)/|ψ|²`, so the
+/// residual sheds `2π`.
+fn residual(grid: Grid<'_>) -> (Vec, Vec) {
+ let (mut turns, mut prev) = (0.0, 0.0);
+ grid.psi
+ .iter()
+ .zip(grid.d)
+ .enumerate()
+ .map(|(i, (&psi, &d))| {
+ let (s, c) = (TAU * i as f64 * grid.du).sin_cos();
+ let raw = (psi * Complex64::new(c, -s)).arg();
+ turns -= TAU * ((raw - prev) / TAU).round();
+ prev = raw;
+ (
+ raw + turns,
+ TAU * ((psi.re * d.re + psi.im * d.im) / psi.norm_sqr() - 1.0),
+ )
+ })
+ .unzip()
+}
+
+/// `|ψ|` and `d|ψ|/du` = `Re(conj(ψ)·ψ')/|ψ| with ψ' = 2πi d`.
+fn magnitude(grid: Grid<'_>) -> (Vec, Vec) {
+ grid.psi
+ .iter()
+ .zip(grid.d)
+ .map(|(&psi, &d)| {
+ let a = psi.norm();
+ (a, TAU * (psi.im * d.re - psi.re * d.im) / a)
+ })
+ .unzip()
+}
+
+/// Remaining share g of a tap, held softly over g_min, the share f32 still resolves as a cliff.
+///
+/// ```text
+/// g ≥ 2g_min g
+/// g < 2g_min g_min (1 + e^{g/g_min − 2})
+/// ```
+fn soft_gain(g: f64, g_min: f64) -> f64 {
+ match g >= 2.0 * g_min {
+ true => g,
+ false => (g_min * (1.0 + (g / g_min - 2.0).exp())).min(1.0),
+ }
+}
+
+/// How d is drawn from the emitted ψ. `Envelope` is a basic valid solution. It is generally
+/// outperformed for reassignment by `Folded`, the **default**, which is faster and only slightly
+/// outperformed by `Fitted`.
+#[derive(Clone, Copy)]
+pub enum Derivative {
+ /// Stencil on the envelope demodulated at the carrier.
+ ///
+ /// ```text
+ /// ψ_k = a_k e^{2πikρ}
+ /// b_k = Σ_m c_m (a_{k+m} − a_{k−m})
+ /// d_k = (a_k − (i/ω₀) b_k) e^{2πikρ}
+ /// ```
+ Envelope,
+ /// |ω| smoothed at its kinks, as a real even convolution over the reach.
+ ///
+ /// ```text
+ /// m(ω) = (G_σ ⊛ |ω|) / ω₀, σ = min(ω̄, π − ω̄) / sigmas
+ /// ```
+ ///
+ /// Even, so a real tone reads D = m(ω) Ψ at every phase.
+ Folded { sigmas: f64 },
+ /// Weighted least squares over the reach against |ω| H.
+ ///
+ /// ```text
+ /// min_d Σ_ω W(ω) |H_d(ω) − (|ω|/ω₀) H(ω)|²
+ /// W(ω) = 1 / (H(|ω|)² + ε²), ε = PEAK_GAIN · 10^{gate_db/20}
+ /// ```
+ ///
+ /// W reads bias at +ω and image residual at −ω against the tone's own H(|ω|).
+ Fitted { gate_db: f64 },
+}
+
+impl Default for Derivative {
+ fn default() -> Self {
+ Self::Folded { sigmas: 6.0 }
+ }
+}
+
+impl Derivative {
+ /// Writes `psi.len()` folded weights of d reading ω/ω₀. `rho` is the envelope carrier.
+ pub(super) fn write(self, psi: &[Complex64], rho: f64, w0: f64, out: &mut [Complex64]) {
+ match self {
+ Derivative::Envelope => envelope(psi, rho, w0, out),
+ Derivative::Folded { sigmas } => folded(psi, w0, sigmas, out),
+ Derivative::Fitted { gate_db } => fitted(psi, w0, gate_db, out),
+ }
+ }
+}
+
+/// Central first difference, order 2·len.
+const STENCIL: [f64; 3] = [0.75, -0.15, 1.0 / 60.0];
+
+/// ```text
+/// ψ_k = a_k e^{2πikρ}
+/// b_k = Σ_m c_m (a_{k+m} − a_{k−m})
+/// d_k = (2πρ a_k − i b_k) e^{2πikρ} / ω₀
+/// ```
+fn envelope(psi: &[Complex64], rho: f64, w0: f64, out: &mut [Complex64]) {
+ let k = psi.len();
+
+ // a_j = ψ_j e^{-2πijρ}, Hermitian
+ let at = |j: isize| {
+ let m = j.unsigned_abs();
+ if m >= k {
+ return Complex64::default();
+ }
+ let (s, c) = (TAU * m as f64 * rho).sin_cos();
+ let a = psi[m] * Complex64::new(c, -s);
+ if j < 0 {
+ a.conj()
+ } else {
+ a
+ }
+ };
+
+ let carrier = TAU * rho;
+ let inv = w0.recip();
+
+ for (j, o) in out.iter_mut().enumerate() {
+ let n = j as isize;
+ let b: Complex64 = STENCIL
+ .iter()
+ .enumerate()
+ .map(|(i, &c)| {
+ let m = i as isize + 1;
+ c * (at(n + m) - at(n - m))
+ })
+ .sum();
+
+ let (s, c) = (TAU * j as f64 * rho).sin_cos();
+ *o = (carrier * at(n) - Complex64::i() * b) * inv * Complex64::new(c, s);
+ }
+}
+
+/// `ψ_j` over the mirror, zero past the reach.
+fn unfold(psi: &[Complex64], j: isize) -> Complex64 {
+ match psi.get(j.unsigned_abs()) {
+ Some(&p) if j < 0 => p.conj(),
+ Some(&p) => p,
+ None => Complex64::default(),
+ }
+}
+
+/// `ω̄` = `arg Σ_ν ψ_{ν+1} conj ψ_ν`, the circular mean of `|H|²`
+fn centroid(psi: &[Complex64]) -> f64 {
+ psi.windows(2)
+ .map(|p| p[1] * p[0].conj())
+ .sum::()
+ .arg()
+}
+
+/// `d_k = Σ_n h_n ψ_{k−n} / ω₀`
+fn folded(psi: &[Complex64], w0: f64, sigmas: f64, out: &mut [Complex64]) {
+ let reach = psi.len() as isize;
+ let wc = centroid(psi);
+ let sigma = wc.min(PI - wc) / sigmas;
+
+ // G_σ ⊛ |ω| = π/2 − (4/π) Σ_{n odd} e^{−σ²n²/2} cos(nω) / n²
+ let h: Vec = (0..2 * reach - 1)
+ .map(|n| match n {
+ 0 => FRAC_PI_2,
+ n if n % 2 == 0 => 0.0,
+ n => {
+ let n = n as f64;
+ -2.0 / (PI * n * n) * (-0.5 * (sigma * n).powi(2)).exp()
+ }
+ })
+ .collect();
+
+ for (k, o) in out.iter_mut().enumerate() {
+ let k = k as isize;
+ *o = ((k + 1 - reach)..(k + reach))
+ .map(|n| h[n.unsigned_abs()] * unfold(psi, k - n))
+ .sum::()
+ / w0;
+ }
+ out[0].im = 0.0;
+}
+
+/// Frequency samples per unfolded tap in the fit.
+const FIT_OVERSAMPLE: usize = 4;
+
+/// Normal equations over ω_j = 2πj/M.
+///
+/// ```text
+/// Σ_μ ŵ(ν − μ) d_μ = b_ν
+/// ŵ(n) = Σ_j W_j cos(ω_j n), b_ν = Σ_j W_j T_j e^{iω_j ν}, T = (|ω|/ω₀) H
+/// ```
+fn fitted(psi: &[Complex64], w0: f64, gate_db: f64, out: &mut [Complex64]) {
+ let reach = psi.len();
+ let span = 2 * reach - 1;
+ let m = (FIT_OVERSAMPLE * span).next_power_of_two();
+ let eps = PEAK_GAIN * 10f64.powf(gate_db / 20.0);
+
+ // H(ω_j)
+ let fold = Fold::new(psi);
+ let h: Vec = (0..m)
+ .map(|j| fold.dtft(TAU * j as f64 / m as f64))
+ .collect();
+
+ let mut r = vec![0.0; span];
+ let mut b = vec![Complex64::default(); reach];
+ for (j, &hj) in h.iter().enumerate() {
+ // |ω_j| on the mirror
+ let pos = j.min(m - j);
+ let w = (h[pos] * h[pos] + eps * eps).recip();
+ let wt = w * hj * TAU * pos as f64 / (m as f64 * w0);
+
+ // e^{iω_j n}
+ let step = Complex64::from_polar(1.0, TAU * j as f64 / m as f64);
+ let mut rot = Complex64::new(1.0, 0.0);
+ for (rn, bn) in r.iter_mut().zip(b.iter_mut()) {
+ *rn += w * rot.re;
+ *bn += wt * rot;
+ rot *= step;
+ }
+ for rn in &mut r[reach..] {
+ *rn += w * rot.re;
+ rot *= step;
+ }
+ }
+
+ // n = ν + K − 1, b_{−ν} = conj b_ν
+ let mut rhs = vec![Complex64::default(); span];
+ for (v, &bv) in b.iter().enumerate() {
+ rhs[reach - 1 + v] = bv;
+ rhs[reach - 1 - v] = bv.conj();
+ }
+
+ let d = levinson(&r, &rhs);
+ out.copy_from_slice(&d[reach - 1..]);
+ out[0].im = 0.0;
+}
+
+/// `x` with `Σ_j r_{|i−j|} x_j = y_i`, `r` symmetric positive definite Toeplitz.
+fn levinson(r: &[f64], y: &[Complex64]) -> Vec {
+ let n = y.len();
+ let r0 = r[0];
+ let t = |i: usize| r[i] / r0;
+
+ let mut x = Vec::with_capacity(n);
+ let mut v = Vec::with_capacity(n);
+ x.push(y[0] / r0);
+ v.push(-t(1));
+ let (mut alpha, mut beta) = (-t(1), 1.0);
+
+ for k in 1..n {
+ beta *= 1.0 - alpha * alpha;
+
+ let mu = (y[k] / r0 - (0..k).map(|i| t(i + 1) * x[k - 1 - i]).sum::()) / beta;
+ for i in 0..k {
+ x[i] += mu * v[k - 1 - i];
+ }
+ x.push(mu);
+
+ if k < n - 1 {
+ alpha = (-t(k + 1) - (0..k).map(|i| t(i + 1) * v[k - 1 - i]).sum::()) / beta;
+ for i in 0..k / 2 {
+ let (a, c) = (v[i], v[k - 1 - i]);
+ v[i] = a + alpha * c;
+ v[k - 1 - i] = c + alpha * a;
+ }
+ if k % 2 == 1 {
+ v[k / 2] *= 1.0 + alpha;
+ }
+ v.push(alpha);
+ }
+ }
+ x
+}
+
+#[cfg(test)]
+mod test {
+ use super::super::{
+ harness::{at, weighted_quantile, Ledger},
+ inspect::{bisect, characterize, db},
+ Bake, Fold, Shape, WaveletSpec,
+ };
+ use super::*;
+
+ const TAIL_DB: f64 = -60.0;
+ const GAMMAS: [f64; 3] = [2.0, 3.0, 4.0];
+ const QS: [f64; 4] = [3.5, 5.0, 8.5, 12.5];
+ const RHOS: [f64; 10] = [
+ 0.02, 0.06, 0.116, 0.189, 0.25, 0.312, 0.384, 0.42, 0.44, 0.46,
+ ];
+ /// Taps below this fraction of the lane's crest do not vote on rise.
+ const GATE: f64 = 1e-6;
+ /// Worst readings printed per limit.
+ const WORST: usize = 4;
+
+ const QUADRATURES: [(&str, Quadrature); 4] = [
+ ("nearest", Quadrature::Nearest),
+ ("complex", Quadrature::Complex),
+ ("axial", Quadrature::Axial),
+ ("weighted", Quadrature::Weighted),
+ ];
+
+ const TAPERS: [(&str, Taper); 3] = [
+ ("rect", Taper::Rectangle),
+ ("cyl", Taper::Cylinder),
+ ("knee", Taper::Knee { curvature: 1.0 }),
+ ];
+
+ /// Quadrature major, `rect` first within each quadrature.
+ fn methods() -> Vec<(String, Restriction)> {
+ QUADRATURES
+ .into_iter()
+ .flat_map(|(qn, quadrature)| {
+ TAPERS.into_iter().map(move |(tn, taper)| {
+ let r = Restriction {
+ quadrature,
+ taper,
+ ..Default::default()
+ };
+ (format!("{qn}/{tn}"), r)
+ })
+ })
+ .collect()
+ }
+
+ /// ω of the tilted crest on (ω₀/4, ω₀).
+ ///
+ /// ```text
+ /// (ln Ψ)' + (ln K)' = 0
+ /// (ln Ψ)' = β/ω − (β/ω₀)(ω/ω₀)^{γ−1}
+ /// Complex (ln K)' = ½ cot(ω/2) − 1/ω
+ /// Weighted (ln K)' = ½ cot(ω/2) − 1/ω − tan(ω/2)
+ /// ```
+ fn tilted_crest(quadrature: Quadrature, shape: Shape, w0: f64) -> f64 {
+ let (beta, gamma) = (shape.beta, shape.gamma);
+ let box_ = |w: f64| 0.5 / (0.5 * w).tan() - 1.0 / w;
+ let tilt = |w: f64| match quadrature {
+ Quadrature::Nearest | Quadrature::Axial => 0.0,
+ Quadrature::Complex => box_(w),
+ Quadrature::Weighted => box_(w) - (0.5 * w).tan(),
+ };
+ bisect(
+ |w| beta / w - beta / w0 * (w / w0).powf(gamma - 1.0) + tilt(w),
+ 0.25 * w0,
+ w0,
+ )
+ }
+
+ /// One lane at (γ, Q, ρ).
+ ///
+ /// ```text
+ /// crest 1200 log₂(ω_peak / ω_K), ω_K the kernel tilted Morse crest
+ /// image |H(−ω₀)| / H(ω_peak)
+ /// floor stopband floor / H(ω_peak)
+ /// body ‖|h| − |h_rect|‖ / ‖h_rect‖, h_rect the same quadrature untapered
+ /// rise max_k ln(|h_{k+1}| / |h_k|)
+ /// ```
+ struct Reading {
+ at: (f64, f64, f64),
+ /// Under the shape's fold ceiling, where the noise floor is promised.
+ within: bool,
+ finite: bool,
+ crest: f64,
+ image: f64,
+ floor: f64,
+ body: f64,
+ rise: f64,
+ }
+
+ fn read(
+ at: (f64, f64, f64),
+ within: bool,
+ lane: &[Complex64],
+ mag: &[f64],
+ rect: &[f64],
+ quadrature: Quadrature,
+ shape: Shape,
+ w0: f64,
+ ) -> Reading {
+ if !lane.iter().all(|h| h.is_finite()) {
+ return Reading {
+ at,
+ within,
+ finite: false,
+ crest: f64::NAN,
+ image: f64::NAN,
+ floor: f64::NAN,
+ body: f64::NAN,
+ rise: f64::NAN,
+ };
+ }
+
+ let psi = Fold::new(lane);
+ let r = characterize(psi, w0);
+ let target = tilted_crest(quadrature, shape, w0);
+
+ // ‖|h| − |h_rect|‖ / ‖h_rect‖
+ let rect_l2 = rect.iter().map(|a| a * a).sum::().sqrt();
+ let body = mag
+ .iter()
+ .zip(rect)
+ .map(|(a, e)| (a - e).powi(2))
+ .sum::()
+ .sqrt()
+ / rect_l2;
+
+ let top = mag.iter().fold(0.0f64, |a, &b| a.max(b));
+ let rise = mag
+ .windows(2)
+ .filter(|p| p[0].min(p[1]) >= GATE * top)
+ .map(|p| (p[1] / p[0]).ln())
+ .fold(f64::NEG_INFINITY, f64::max);
+
+ Reading {
+ at,
+ within,
+ finite: true,
+ crest: 1200.0 * (r.peak_w / target).log2(),
+ image: db(psi.dtft(-w0).abs()) - db(r.gain),
+ floor: db(r.floor) - db(r.gain),
+ body,
+ rise,
+ }
+ }
+
+ /// Every method over γ × Q × ρ, unrefined, one row per bin naming its worst lanes. Rows past
+ /// the shape's fold ceiling are starred.
+ fn sweep(methods: &[(String, Restriction)]) -> Vec> {
+ let mut bake = Bake::default();
+ let mut readings: Vec> = methods.iter().map(|_| Vec::new()).collect();
+
+ println!(
+ "\n=== RESTRICTION SANITY (tail {TAIL_DB:.0} dB, {} methods, unrefined) ===",
+ methods.len()
+ );
+ println!(" * past the fold ceiling, reported but not toleranced");
+ println!(
+ " {:>4} {:>5} {:>7} {:>7} {:>5} {:>8} {:>16} {:>9} {:>9} {:>9} {:>16} {:>9}",
+ "γ",
+ "Q",
+ "ceiling",
+ "ρ",
+ "taps",
+ "crest c",
+ "worst",
+ "image",
+ "floor",
+ "body",
+ "worst",
+ "rise"
+ );
+
+ for gamma in GAMMAS {
+ for q in QS {
+ let shape = Shape::from_q(q, gamma);
+ let mut wav = WaveletSpec::default()
+ .shape(shape)
+ .max_truncation(TAIL_DB)
+ .bake();
+ wav.refinement = None;
+ let ceiling = shape.fold_ceiling(wav.limits.noise_floor);
+
+ for rho in RHOS {
+ let (w0, within) = (TAU * rho, rho <= ceiling);
+
+ let lanes: Vec> = methods
+ .iter()
+ .map(|&(_, r)| {
+ wav.restriction = r;
+ wav.at_rho(rho).write(&mut bake);
+ bake.weights.psi.clone()
+ })
+ .collect();
+ let mags: Vec> = lanes
+ .iter()
+ .map(|l| l.iter().map(|h| h.norm()).collect())
+ .collect();
+
+ let row: Vec = methods
+ .iter()
+ .enumerate()
+ .map(|(i, (_, r))| {
+ let rect = &mags[i - i % TAPERS.len()];
+ read(
+ (gamma, q, rho),
+ within,
+ &lanes[i],
+ &mags[i],
+ rect,
+ r.quadrature,
+ shape,
+ w0,
+ )
+ })
+ .collect();
+
+ // worst lane of one column
+ let worst = |f: fn(&Reading) -> f64| {
+ row.iter()
+ .zip(methods)
+ .map(|(r, (n, _))| (f(r), n.as_str()))
+ .fold(
+ (f64::NEG_INFINITY, ""),
+ |a, b| if b.0 > a.0 { b } else { a },
+ )
+ };
+ let crest = worst(|r| r.crest.abs());
+ let body = worst(|r| r.body);
+
+ println!(
+ " {gamma:>4.1} {q:>5.1} {ceiling:>7.3} {rho:>6.3}{} {:>5} {:>8.3} {:>16} \
+ {:>9.2} {:>9.2} {:>9.2e} {:>16} {:>9.2e}",
+ if within { ' ' } else { '*' },
+ 2 * lanes[0].len() - 1,
+ crest.0,
+ crest.1,
+ worst(|r| r.image).0,
+ worst(|r| r.floor).0,
+ body.0,
+ body.1,
+ worst(|r| r.rise).0,
+ );
+
+ for (acc, r) in readings.iter_mut().zip(row) {
+ acc.push(r);
+ }
+ }
+ }
+ }
+ readings
+ }
+
+ /// Median and worst per method over the readings `keep` admits.
+ fn report(
+ title: &str,
+ methods: &[(String, Restriction)],
+ readings: &[Vec],
+ keep: fn(&Reading) -> bool,
+ ) {
+ println!("\n {title}, median / worst over γ × Q × ρ");
+ println!(
+ " {:>16} {:>17} {:>17} {:>17} {:>21} {:>21}",
+ "method", "crest c", "image dB", "floor dB", "body", "rise"
+ );
+
+ for ((name, _), rs) in methods.iter().zip(readings) {
+ // (median, worst)
+ let col = |f: fn(&Reading) -> f64| {
+ let mut v: Vec<(f64, f64)> =
+ rs.iter().filter(|r| keep(r)).map(|r| (1.0, f(r))).collect();
+ let worst = v.iter().map(|r| r.1).fold(f64::NEG_INFINITY, f64::max);
+ (weighted_quantile(&mut v, 0.5), worst)
+ };
+ let (crest, image, floor) =
+ (col(|r| r.crest.abs()), col(|r| r.image), col(|r| r.floor));
+ let (body, rise) = (col(|r| r.body), col(|r| r.rise));
+
+ println!(
+ " {name:>16} {:>17} {:>17} {:>17} {:>21} {:>21}",
+ format!("{:.3} / {:.3}", crest.0, crest.1),
+ format!("{:.1} / {:.1}", image.0, image.1),
+ format!("{:.1} / {:.1}", floor.0, floor.1),
+ format!("{:.2e} / {:.2e}", body.0, body.1),
+ format!("{:.2e} / {:.2e}", rise.0, rise.1),
+ );
+ }
+ }
+
+ /// One ledger of err / tol per limit over the readings `keep` admits, returning whether every
+ /// reading holds.
+ fn judge(
+ readings: &[Vec],
+ keep: fn(&Reading) -> bool,
+ limits: &[(&str, &dyn Fn(&Reading) -> f64)],
+ ) -> bool {
+ let mut held = true;
+ for (label, ratio) in limits {
+ let mut ledger = Ledger::default();
+ for (i, rs) in readings.iter().enumerate() {
+ let (quadrature, taper) = (i / TAPERS.len(), i % TAPERS.len());
+ for r in rs.iter().filter(|r| keep(r)) {
+ let (gamma, q, rho) = r.at;
+ ledger.record(1.0, ratio(r), at!(gamma, q, rho, quadrature, taper));
+ }
+ }
+ println!("\n {label} good {:.4}", ledger.good());
+ ledger.print_worst(WORST);
+ held &= ledger.good() == 1.0;
+ }
+ held
+ }
+
+ /// Sanity across every quadrature and taper over γ × Q × ρ, restriction alone. Tolerances
+ /// hold under each shape's fold ceiling. Past it every method degrades, so only broken taps
+ /// fail there.
+ #[test]
+ fn restrictions_are_sane() {
+ // Measured 2.63c taper skew at γ 4, Q 3.5.
+ const CREST_C: f64 = 3.5;
+ // Measured −46.3 dB at γ 2, Q 3.5, ρ 0.384, since found past the ceiling.
+ const IMAGE_DB: f64 = -40.0;
+ // Measured 1.58e-2, knee.
+ const BODY_TOL: f64 = 2e-2;
+ // Measured no outward rise.
+ const RISE_TOL: f64 = 1e-9;
+
+ let methods = methods();
+ let readings = sweep(&methods);
+ report("WITHIN CEILING", &methods, &readings, |r| r.within);
+ report("PAST CEILING", &methods, &readings, |r| !r.within);
+
+ let finite = judge(
+ &readings,
+ |_| true,
+ &[("finite", &|r| if r.finite { 0.0 } else { f64::INFINITY })],
+ );
+ let held = judge(
+ &readings,
+ |r| r.within,
+ &[
+ ("crest", &|r| r.crest.abs() / CREST_C),
+ // 10^{(image − limit)/20}
+ ("image", &|r| 10f64.powf((r.image - IMAGE_DB) / 20.0)),
+ ("body", &|r| r.body / BODY_TOL),
+ ("rise", &|r| r.rise.max(0.0) / RISE_TOL),
+ ],
+ );
+ assert!(finite, "non-finite taps");
+ assert!(
+ held,
+ "readings past their limits under the ceiling, worst listed per limit"
+ );
+ }
+}
diff --git a/mutate-lib/src/dsp/wavelet/spec.rs b/mutate-lib/src/dsp/wavelet/spec.rs
new file mode 100644
index 00000000..d3cef89c
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/spec.rs
@@ -0,0 +1,578 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # Spec
+//!
+//! > We reject: kings, presidents, and voting.
+//! > We believe in: rough consensus and running code
+//! >
+//! > - David "D" Clark
+//!
+//! The specs only encapsulate the related decisions that go into generating a wavelet family or
+//! similar set of bins. See the parent module for usage.
+
+// NEXT PSL is perhaps a better measure when planning for useful dynamic range because the skirt
+// rolls off quite deeply for some filters, depending on the truncation performance etc. After
+// adding some spectral cleanup, we'll see where the numbers and shapes land. Tighter side lobe and
+// shaping the garbage on the noise floor is probably something that can be bought.
+// MAYBE Contradictory specification goals (eg max delay + min Q) would require some restructuring to
+// form a consistent API. That is mostly a decision for planning a filter bank, not an individual
+// filter. The implementation may be incomplete or the need may be addressed downstream.
+// DEBT Noise floor / truncation is among one of the contradictory specification goals. It should
+// be just fine, but currently the units don't match and just got a bit lucky, being pseudolinear
+// enough to appear to be working. As truncation bites harder, the main lobe gets wider and centers
+// try to wander.
+
+use core::f64::consts::{FRAC_2_SQRT_PI, LN_10, LN_2, PI, TAU};
+use core::ops::Range;
+
+use libm::{erfc, lgamma};
+use num_complex::Complex64;
+
+use super::defaults;
+use super::generate::quadjet::QuadJet;
+use super::inspect::bisect;
+use super::refine;
+use super::restrict;
+use super::{Bin, Wavelet, PEAK_GAIN};
+
+/// Neper is the natural-log analogue of the decibel. It is not a beloved unit, but simplifies
+/// expressions in some domains.
+const DB_PER_NP: f64 = 20.0 / LN_10;
+/// Deepest noise floor an `f32` table can reliably express against `PEAK_GAIN`.
+pub const NOISE_FLOOR_LIMIT_DB: f64 = -160.0;
+/// Truncation sits this far under the noise floor, keeping the fold the binding feature and the
+/// delivered −3 dB width faithful to Q.
+pub(crate) const TAIL_OVER_FLOOR_DB: f64 = -10.0;
+/// Lowest Q whose envelope spans enough carrier periods to hold its shape. Under it the crest
+/// leaves ω₀ and the skirt never reaches a floor.
+pub const Q_FLOOR: f64 = 2.5;
+/// Temporary calibration for Q effective, which is proportionate, not equal to N^{-3/2}.
+pub const Q_REASSIGNMENT_CAL: f64 = 1.0;
+
+/// Saddle continuation steps per envelope sigma.
+const SADDLE_STEPS: f64 = 4.0;
+const SADDLE_NEWTON: usize = 3;
+
+/// |ψ|² at t = 2πu/ω_p as saddle and endpoint parts, logs in the units of Ψ = ω^β e^{−ω^γ}.
+struct Parts {
+ t: f64,
+ /// ω_s
+ w: Complex64,
+ /// φ''(ω_s)
+ c: Complex64,
+ /// ln |ψ_s|², scaled to the exact ψ(0)
+ saddle: f64,
+ /// ln |ψ_a|², −∞ before Watson
+ endpoint: f64,
+}
+
+/// Controls Q and other critical tradeoffs of the Morse family wavelet parameters. For exact
+/// details, consult [real graphs](https://arxiv.org/pdf/1203.3380).
+#[derive(Clone, Copy)]
+pub struct Shape {
+ /// The 𝛄 value of 3 results in a useful frequency domain uniformity and is the standard choice.
+ /// Higher values have slightly different asymmetry but give tighter main lobes. Both `gamma` and
+ /// `beta` cost taps via the `p` factor in downstream calculations, so do your homework.
+ pub gamma: f64,
+ /// Adjusting beta at fixed gamma is adjusting Q. The same envelope shape will be dilated over
+ /// more carrier periods, resulting in more taps required to approximate the wavelet, the
+ /// familiar time vs pitch resolution tradeoff.
+ pub beta: f64,
+}
+
+impl Shape {
+ /// `q` is the quality factor `fc / BW` on the half-power bandwidth. Higher `q` narrows the
+ /// band and costs proportionally more taps at a given center frequency.
+ ///
+ /// The width at the start of the skirt, which must be controlled to avoid transition bands of
+ /// downsampled inputs, is usually not more than `2 fc / q`.
+ pub const fn from_q(q: f64, gamma: f64) -> Self {
+ // DEBT QuadJet's saddle handling or Stokes table march is the weakness. We may be able to
+ // disable the Jet for non-integral gamma, falling back to pure quadrature, or use feature
+ // gating and fall back to IFFT. To the extent that real gamma would be useful, the refine
+ // module can probably pick up the slack. Technically QuadJet is only valid for gamma >=
+ // 3.0, but tell that to the wavelets it successfully produces.
+ debug_assert!(gamma.trunc() == gamma, "QuadJet requires integral gamma");
+
+ // p = 2.0 * LN_2.sqrt() * q
+ // beta = p * p / gamma
+ Shape {
+ gamma,
+ beta: (4.0 * LN_2) * (q * q / gamma),
+ }
+ }
+
+ /// Least shape holding the Nyquist fold at or below `noise_floor` for every bin up to
+ /// `max_rho`.
+ ///
+ /// ```text
+ /// β D(1/2ρ, γ) = |floor| ln10 / 20
+ /// ```
+ pub fn from_noise_floor(max_rho: f64, noise_floor: f64, gamma: f64) -> Self {
+ // DEBT This method is just overall not that great. It slipped through smoke tests but
+ // doesn't seem very accurate or precise compared to some of the other analytic tools in our
+ // box.
+
+ let db = noise_floor.abs().min(NOISE_FLOOR_LIMIT_DB.abs());
+ let shape = Shape {
+ gamma,
+ beta: db / (DB_PER_NP * fold_cost(0.5 / max_rho, gamma)),
+ };
+ debug_assert!(
+ shape.q() >= Q_FLOOR,
+ "floor {noise_floor:.1} at rho {max_rho} wants Q {:.2}, under the family's {Q_FLOOR}",
+ shape.q()
+ );
+ shape
+ }
+
+ /// Morse wavelet time-bandwidth product (P = √(βγ)). It can be interpreted as a surrogate for
+ /// Q.
+ pub fn p(&self) -> f64 {
+ (self.beta * self.gamma).sqrt()
+ }
+
+ /// Return the **estimated** `q` for this shape. Realized `q` will be close.
+ pub fn q(&self) -> f64 {
+ self.p() / (2.0 * LN_2.sqrt())
+ }
+
+ /// `ω_p = (β/γ)^{1/γ}`, argmax of `ω^β e^{-ω^γ}` and the frequency `u` counts cycles of.
+ pub fn peak(&self) -> f64 {
+ if self.gamma == 3.0 {
+ // cbrt is just the fast path
+ (self.beta / 3.0).cbrt()
+ } else {
+ (self.beta / self.gamma).powf(1.0 / self.gamma)
+ }
+ }
+
+ /// M_k = 0, Ψ⁽ᵏ⁾(0) = 0, k < β
+ ///
+ /// ∫ |t|ᵏ |ψ| is finite over the same range, |ψ(t)| ~ |t|^{−(β+1)}.
+ pub fn vanishing_moments(&self) -> Range {
+ 0..self.beta.ceil() as u32
+ }
+
+ /// ∫ |t|ᵏ |ψ|² finite, k < 2β + 1
+ pub fn energy_moments(&self) -> Range {
+ 0..(2.0 * self.beta + 1.0).ceil() as u32
+ }
+
+ /// Nyquist fold of a bin at `rho`, in dB under the passband crest.
+ ///
+ /// ```text
+ /// H(−π) / H(ω₀) = Ψ(ω_p/2ρ) / Ψ(ω_p)
+ /// ```
+ pub(super) fn image_db(&self, rho: f64) -> f64 {
+ -DB_PER_NP * self.beta * fold_cost(0.5 / rho, self.gamma)
+ }
+
+ /// Highest ρ whose Nyquist fold holds `noise_floor`, the inverse of `from_noise_floor`.
+ ///
+ /// ```text
+ /// ρ = 1 / 2D⁻¹(|floor| ln10 / 20β, γ)
+ /// ```
+ pub fn fold_ceiling(&self, noise_floor: f64) -> f64 {
+ 0.5 / fold_reach(noise_floor.abs() / (DB_PER_NP * self.beta), self.gamma)
+ }
+
+ /// White noise gain of a bin at `rho`, what a unit variance input reads as |Ψ|².
+ ///
+ /// ```text
+ /// Σ_ν |ψ_ν|² = ρ G² Γ(r) s^{−r} e^s / γ, s = 2β/γ, r = s + 1/γ
+ /// ```
+ pub fn noise_gain(&self, rho: f64) -> f64 {
+ let s = 2.0 * self.beta / self.gamma;
+ let r = s + self.gamma.recip();
+ rho * PEAK_GAIN * PEAK_GAIN * (lgamma(r) - r * s.ln() + s).exp() / self.gamma
+ }
+
+ /// Crest SNR of a complex tone at `snr_db` per sample against white noise.
+ ///
+ /// ```text
+ /// SNR_out = SNR_in G² / Σ|ψ_ν|²
+ /// ```
+ pub fn snr_out(&self, rho: f64, snr_db: f64) -> f64 {
+ 10f64.powf(snr_db / 10.0) * PEAK_GAIN * PEAK_GAIN / self.noise_gain(rho)
+ }
+
+ /// Reassigned pitch resolution in the half-power width units of `q`.
+ ///
+ /// ```text
+ /// σ_r² = ½ (σ_ω / ω₀)² / SNR_out, σ_ω = ω_p / √2 P
+ /// Qeff = 2 Q √SNR_out
+ /// ```
+ pub fn q_reassignment(&self, rho: f64, snr_db: f64) -> f64 {
+ Q_REASSIGNMENT_CAL * 2.0 * self.q() * self.snr_out(rho, snr_db).sqrt()
+ }
+
+ /// φ'' = −β/ω² − γ(γ−1)ω^{γ−2}
+ fn curvature(&self, w: Complex64) -> Complex64 {
+ let Shape { beta, gamma } = *self;
+ -beta / (w * w) - gamma * (gamma - 1.0) * w.powf(gamma - 2.0)
+ }
+
+ /// ω_s solving β/ω − γω^{γ−1} + it = 0, continued from ω_p at t = 0.
+ fn saddle(&self, t: f64) -> Complex64 {
+ let Shape { beta, gamma } = *self;
+ // t / σ_t, σ_t = P / ω_p
+ let steps = (SADDLE_STEPS * t * self.peak() / self.p()).ceil().max(1.0) as usize;
+ let mut w = Complex64::new(self.peak(), 0.0);
+ for s in 1..=steps {
+ let it = Complex64::new(0.0, t * s as f64 / steps as f64);
+ for _ in 0..SADDLE_NEWTON {
+ w -= (beta / w - gamma * w.powf(gamma - 1.0) + it) / self.curvature(w);
+ }
+ }
+ w
+ }
+
+ /// ln |ψ(0)|² = 2 ln(Γ((β+1)/γ) / 2πγ)
+ fn ln_center(&self) -> f64 {
+ 2.0 * (lgamma((self.beta + 1.0) / self.gamma) - self.gamma.ln() - TAU.ln())
+ }
+
+ fn parts(&self, u: f64) -> Parts {
+ let Shape { beta, gamma } = *self;
+ let (wp, p) = (self.peak(), self.p());
+ let t = TAU * u / wp;
+
+ // ln |ψ(0)|² exact over saddle
+ let k0 = self.ln_center()
+ - (2.0 * (beta * wp.ln() - beta / gamma) - TAU.ln() - 2.0 * (p / wp).ln());
+
+ let w = self.saddle(t);
+ let c = self.curvature(w);
+ let phi = beta * w.ln() - w.powf(gamma) + Complex64::new(0.0, t) * w;
+ let watson = ((lgamma(beta + 1.0 + gamma) - lgamma(beta + 1.0)) / gamma).exp();
+
+ Parts {
+ t,
+ w,
+ c,
+ saddle: 2.0 * phi.re - TAU.ln() - c.norm().ln() + k0,
+ // |ψ_a|² = Γ(β+1)² / 4π² t^{2β+2}
+ endpoint: match t > watson {
+ true => 2.0 * lgamma(beta + 1.0) - 2.0 * TAU.ln() - 2.0 * (beta + 1.0) * t.ln(),
+ false => f64::NEG_INFINITY,
+ },
+ }
+ }
+
+ /// ln(a(u)/a(0)) and the elasticity −u a'/a of the envelope.
+ ///
+ /// ```text
+ /// |ψ|² = |ψ_s|² + |ψ_a|²
+ /// s = (|ψ_s|² t Im ω_s + |ψ_a|² (β + 1)) / |ψ|²
+ /// ```
+ pub fn envelope(&self, u: f64) -> (f64, f64) {
+ let e = self.parts(u);
+ let total = log_add(e.saddle, e.endpoint);
+ // endpoint share of |ψ|²
+ let share = (e.endpoint - total).exp();
+ let s = (1.0 - share) * e.t * e.w.im + share * (self.beta + 1.0);
+ (0.5 * (total - self.ln_center()), s)
+ }
+
+ /// Energy outside ±u carrier periods as a share of the whole, in dB.
+ ///
+ /// ```text
+ /// f' = −2 Im ω_s, f'' = 2 Re 1/φ''
+ /// ∫_T^∞ |ψ_s|² = |ψ_s(T)|² √(π / 2|f''|) erfcx(|f'| / √(2|f''|))
+ /// ∫_T^∞ |ψ_a|² = |ψ_a(T)|² T / (2β + 1)
+ /// μ = ∫_T^∞ (|ψ_s|² + |ψ_a|²) / ½∫|ψ|²
+ /// ```
+ pub fn truncation_tail(&self, u: f64) -> f64 {
+ let Shape { beta, gamma } = *self;
+ let e = self.parts(u);
+
+ // |f'|, |f''|
+ let (a, b) = (2.0 * e.w.im, (-2.0 * e.c.inv().re).max(f64::MIN_POSITIVE));
+ let saddle = e.saddle + 0.5 * (PI / (2.0 * b)).ln() + erfcx(a / (2.0 * b).sqrt()).ln();
+ // 2β + 1
+ let n = 2.0 * beta + 1.0;
+ let endpoint = e.endpoint + e.t.ln() - n.ln();
+
+ // ln ½∫|ψ|² = ln Γ(r) − ln γ − r ln 2 − ln 4π, r = (2β + 1)/γ
+ let r = n / gamma;
+ let half = lgamma(r) - gamma.ln() - r * LN_2 - (2.0 * TAU).ln();
+ 0.5 * DB_PER_NP * (log_add(saddle, endpoint) - half)
+ }
+
+ /// Least half span in carrier periods whose `truncation_tail` reaches `tail_db`.
+ pub fn truncation_u(&self, tail_db: f64) -> f64 {
+ let goal = -tail_db.abs();
+ // x = 1, doubled past the goal
+ let mut hi = self.p() / TAU;
+ while self.truncation_tail(hi) > goal {
+ hi *= 2.0;
+ }
+ bisect(|u| self.truncation_tail(u) - goal, 0.0, hi)
+ }
+}
+
+impl Default for Shape {
+ fn default() -> Self {
+ Shape::from_q(defaults::Q, defaults::GAMMA)
+ }
+}
+
+/// (f^γ − 1)/γ − ln f
+fn fold_cost(f: f64, gamma: f64) -> f64 {
+ (f.powf(gamma) - 1.0) / gamma - f.ln()
+}
+
+/// Inverse of `fold_cost` on f ≥ 1.
+fn fold_reach(cost: f64, gamma: f64) -> f64 {
+ // γε²/2 near the crest, (f^γ − 1)/γ away from it
+ let near = 1.0 + (2.0 * cost / gamma).sqrt();
+ let far = (gamma * cost + 1.0).powf(gamma.recip());
+ let mut f = near.max(far);
+ for _ in 0..6 {
+ f -= (fold_cost(f, gamma) - cost) / (f.powf(gamma - 1.0) - f.recip());
+ }
+ f
+}
+
+/// ln(eᵃ + eᵇ)
+fn log_add(a: f64, b: f64) -> f64 {
+ let (hi, lo) = (a.max(b), a.min(b));
+ hi + (lo - hi).exp().ln_1p()
+}
+
+/// e^{y²} erfc(y), y ≥ 0
+fn erfcx(y: f64) -> f64 {
+ match y < 20.0 {
+ true => (y * y).exp() * erfc(y),
+ // (1/y√π)(1 − 1/2y² + 3/4y⁴)
+ false => {
+ let z = (y * y).recip();
+ 0.5 * FRAC_2_SQRT_PI / y * (1.0 - 0.5 * z + 0.75 * z * z)
+ }
+ }
+}
+
+/// The `WaveletSpec` supports
+#[derive(Clone, Copy)]
+pub struct WaveletSpec {
+ pub(super) shape: Shape,
+ pub(super) resolution: usize,
+ pub(super) max_load_quantum: usize,
+ pub(super) max_noise_floor: f64,
+ pub(super) max_half_span: Option,
+ pub(super) max_rho: Option,
+ pub(super) max_delay: usize,
+ pub(super) restriction: restrict::Restriction,
+ pub(super) refinement: Option,
+}
+
+impl Default for WaveletSpec {
+ fn default() -> Self {
+ WaveletSpec {
+ shape: Shape::from_q(defaults::Q, defaults::GAMMA),
+ resolution: defaults::RESOLUTION,
+ max_rho: None,
+ max_noise_floor: defaults::NOISE_FLOOR,
+ max_half_span: None,
+ max_load_quantum: defaults::LOAD_QUANTUM,
+ max_delay: 0,
+ restriction: restrict::Restriction::default(),
+ refinement: Some(refine::Refinement::default()),
+ }
+ }
+}
+
+impl WaveletSpec {
+ /// Set shape by quality factor, holding gamma.
+ pub fn q(mut self, q: f64) -> Self {
+ self.shape = Shape::from_q(q, self.shape.gamma);
+ self
+ }
+
+ /// Set γ, holding Q.
+ pub fn gamma(mut self, gamma: f64) -> Self {
+ self.shape = Shape::from_q(self.shape.q(), gamma);
+ self
+ }
+
+ /// Provide a [`Shape`] directly.
+ pub fn shape(mut self, shape: Shape) -> Self {
+ self.shape = shape;
+ self
+ }
+
+ /// Grid points per period of `u`.
+ pub fn resolution(mut self, resolution: usize) -> Self {
+ self.resolution = resolution;
+ self
+ }
+
+ /// Deepest noise floor any bin will ask for.
+ pub fn max_noise_floor(mut self, db: f64) -> Self {
+ self.max_noise_floor = -(db.abs().min(NOISE_FLOOR_LIMIT_DB.abs()));
+ self
+ }
+
+ /// Longest half span any bin will reach, in carrier periods.
+ pub fn max_half_span(mut self, u: f64) -> Self {
+ self.max_half_span = Some(u);
+ self
+ }
+
+ /// Deepest truncation any bin will ask for, held as the noise floor it lands.
+ pub fn max_truncation(mut self, tail_db: f64) -> Self {
+ self.max_noise_floor = -tail_db.abs() + TAIL_OVER_FLOOR_DB;
+ self
+ }
+
+ /// Highest ρ any bin will ask for. The noise floor holds against the Nyquist fold up to here.
+ pub fn max_rho(mut self, rho: f64) -> Self {
+ self.max_rho = Some(rho);
+ self
+ }
+
+ /// Largest load quantum any bin will ask for.
+ pub fn max_load_quantum(mut self, quantum: usize) -> Self {
+ self.max_load_quantum = quantum;
+ self
+ }
+
+ /// Largest group delay any bin will ask for, in taps.
+ pub fn max_delay(mut self, delay: usize) -> Self {
+ self.max_delay = delay;
+ self
+ }
+
+ /// Set the method for squeezing the high resolution motherlet into `N` taps.
+ pub fn restriction(mut self, restriction: restrict::Restriction) -> Self {
+ self.restriction = restriction;
+ self
+ }
+
+ /// Set the method for restoring some of the pre-truncation transient response characteristics.
+ pub fn refinement(mut self, refine: Option) -> Self {
+ self.refinement = refine;
+ self
+ }
+
+ pub fn bake(self) -> Wavelet {
+ if let Some(rho) = self.max_rho {
+ debug_assert!(
+ self.shape.image_db(rho) <= self.max_noise_floor + 1e-9,
+ "fold {:.1} dB at rho {rho} breaks the {:.1} dB floor",
+ self.shape.image_db(rho),
+ self.max_noise_floor
+ );
+ }
+
+ let du = (self.resolution as f64).recip();
+ let reach = self.max_half_span.unwrap_or_else(|| {
+ self.shape
+ .truncation_u(self.max_noise_floor - TAIL_OVER_FLOOR_DB)
+ });
+ let u_max = reach
+ + self.max_rho.unwrap_or(0.5) * ((self.max_load_quantum + self.max_delay) as f64 + 1.5);
+
+ let jet = QuadJet::standard(self.shape);
+ let (mut psi, mut d): (Vec, Vec) = (0..=(u_max / du).ceil() as usize
+ + 1)
+ .map(|j| {
+ let t = jet.tap_at(j as f64 * du);
+ (t.psi, t.d)
+ })
+ .unzip();
+
+ // Normalize to [0,2) range without touching the mantissas.
+ let peak = psi
+ .iter()
+ .map(|p| p.re.abs().max(p.im.abs()))
+ .fold(0.0f64, f64::max);
+ debug_assert!(peak.is_normal());
+ let exponent = (peak.to_bits() >> 52 & 0x7ff) as i32 - 1023;
+ let scale = 2f64.powi(-exponent);
+ for (p, q) in psi.iter_mut().zip(&mut d) {
+ *p *= scale;
+ *q *= scale;
+ }
+
+ Wavelet {
+ shape: self.shape,
+ du,
+ psi,
+ d,
+ limits: BinSpec {
+ center: self.max_rho.unwrap_or(0.5),
+ rate: 1.0,
+ load_quantum: self.max_load_quantum,
+ delay: self.max_delay,
+ noise_floor: self.max_noise_floor,
+ },
+ restriction: self.restriction,
+ refinement: self.refinement,
+ }
+ }
+}
+
+/// The choices owned by each [`Bin`] that must only be within [`Wavelet`] limits. Not yet tied to
+/// any `Wavelet`, which is where the [`Shape`] geometry comes from.
+#[derive(Clone, Copy)]
+pub struct BinSpec {
+ pub(super) center: f64,
+ pub(super) rate: f64,
+ pub(super) load_quantum: usize,
+ /// Extra group delay, extra folded taps, padding that will be opportunistically used during
+ /// restriction.
+ // XXX has not be reconciled with load quantum!
+ pub(super) delay: usize,
+ pub(super) noise_floor: f64,
+}
+
+impl BinSpec {
+ pub fn new(center: f64, rate: f64) -> Self {
+ debug_assert!(center <= 0.5 * rate);
+ Self {
+ center,
+ rate,
+ load_quantum: defaults::LOAD_QUANTUM,
+ delay: defaults::DELAY,
+ noise_floor: defaults::NOISE_FLOOR,
+ }
+ }
+
+ pub fn load_quantum(self, quantum: usize) -> Self {
+ Self {
+ load_quantum: quantum,
+ ..self
+ }
+ }
+
+ /// Likely not implemented yet
+ pub fn delay(self, delay: usize) -> Self {
+ Self { delay, ..self }
+ }
+
+ pub fn noise_floor(self, db: f64) -> Self {
+ Self {
+ noise_floor: -db.abs(),
+ ..self
+ }
+ }
+
+ pub fn truncate(self, tail_db: f64) -> Self {
+ self.noise_floor(tail_db.abs() - TAIL_OVER_FLOOR_DB)
+ }
+
+ pub fn bin<'w>(self, wavelet: &'w Wavelet) -> Bin<'w> {
+ wavelet.from_spec(self)
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ // As mentioned in the main module, we need behaviors that prevent misuse of `Bin` setters
+ // without checking Wavelet compatibility.
+}
diff --git a/mutate-lib/src/dsp/wavelet/tests/print.rs b/mutate-lib/src/dsp/wavelet/tests/print.rs
new file mode 100644
index 00000000..19540184
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/tests/print.rs
@@ -0,0 +1,201 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # Print Tests
+//!
+//! These tests are primarily diagnostic and do not have much in the way of useful assertions.
+
+use core::f64::consts::{LN_2, PI, TAU};
+
+use super::super::harness::*;
+use super::super::inspect::*;
+use super::super::*;
+
+const RATE: f64 = 48_000.0;
+
+#[ignore]
+#[test]
+fn print_waveform() {
+ const TAIL_DB: f64 = -20.0;
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(4.0, 1.0))
+ .max_truncation(TAIL_DB)
+ .bake();
+
+ for (fc, fs) in [(1000.0f64, 8000.0), (300.0, 3000.0), (12_000.0, RATE)] {
+ let rho = fc / fs;
+ let bin = wav.at_rho(rho);
+ let wts = bin.weights();
+ let (psi, d) = (wts.psi(), wts.d());
+ let w0 = bin.velocity();
+
+ print_wave(
+ &format!(
+ "BIN fc {fc:.0} fs {fs:.0} w0 {w0:.6} rho {rho:.6} taps {}",
+ psi.len_unfolded()
+ ),
+ psi,
+ 30,
+ );
+
+ let g = psi.dtft(w0).abs();
+ let gd = d.dtft(w0).abs();
+ let dc = psi.dtft(0.0);
+ let neg = psi.dtft(-w0).abs();
+
+ // max over m of | |Ψ(m)| − 1 | against cos(ω₀k)
+ let phase_err = (0..8)
+ .map(|m| (wts.project(|k| (w0 * k as f64).cos(), m)[0].norm() - 1.0).abs())
+ .fold(0.0f64, f64::max);
+
+ println!(
+ " peak {g:.9} d/psi {:.9} dc {dc:.3e} neg {:.2} dB phase err {phase_err:.3e}",
+ gd / g,
+ 20.0 * (neg / g).log10()
+ );
+ }
+}
+
+/// Rough magnitude response, centered on the measured peak. The sweep names ρ directly, so
+/// a row is a filter and not a sample rate.
+#[ignore]
+#[test]
+fn print_response() {
+ const Q: f64 = 22.5;
+ const QUANTUM: usize = 4;
+ const TAIL_DB: f64 = -50.0;
+
+ const ROWS: usize = 200;
+ const COLS: usize = 200;
+ const ANTI_ALIAS: usize = 8;
+ const FLOOR_DB: f64 = -120.0;
+ const LOBES: f64 = 96.0;
+
+ // Periods per tap, sweeping the downsample ladder from 20Hz at 3kHz to 15kHz at 48kHz.
+ // Nyquist is 0.5.
+ // const RHOS: [f64; 8] = [0.00667, 0.0116, 0.02, 0.035, 0.060, 0.104, 0.180, 0.312];
+
+ const RHOS: [f64; 1] = [0.312];
+
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(Q, 3.0))
+ .max_load_quantum(QUANTUM)
+ // .max_truncation(TAIL_DB)
+ .max_noise_floor(-100.0)
+ .bake();
+
+ for rho in RHOS {
+ let bin = wav.at_rho(rho);
+ let wts = bin.weights();
+ let psi = wts.psi();
+ let w0 = bin.velocity();
+
+ // 2π/N against the −3 dB width Q asks for
+ let cell = TAU / psi.len_unfolded() as f64;
+ println!(
+ "rho {rho:.4} taps {} cell {cell:.6} requested width {:.6} ({:.2} cells)",
+ psi.len_unfolded(),
+ w0 / Q,
+ w0 / (Q * cell),
+ );
+
+ let r = characterize(psi, w0);
+
+ let lobe = r.edges.1 - r.edges.0;
+ let span = LOBES * lobe;
+ let lo = (r.peak_w - 0.5 * span).max(-PI);
+ let hi = (r.peak_w + 0.5 * span).min(PI);
+ let step = (hi - lo) / ROWS as f64;
+
+ println!(
+ "\n=== RESPONSE rho {rho:.4} taps {} w0 {w0:.6} \
+ lobe {lobe:.6} ({:.5} w/fs) ===",
+ psi.len_unfolded(),
+ lobe / TAU
+ );
+ println!(
+ " columns span {FLOOR_DB:.0} dB (left) to peak (right); \
+ {:.1} of {LOBES:.0} lobes in window",
+ (hi - lo) / lobe
+ );
+
+ for k in 0..=ROWS {
+ let w = lo + step * k as f64;
+
+ // (1/step) ∫ |H(ω)|² dω over [w − step/2, w + step/2]
+ let power = (0..ANTI_ALIAS)
+ .map(|j| {
+ let u = w + step * ((j as f64 + 0.5) / ANTI_ALIAS as f64 - 0.5);
+ psi.dtft(u).powi(2)
+ })
+ .sum::()
+ / ANTI_ALIAS as f64;
+ let level = 10.0 * (power / (r.gain * r.gain)).log10();
+
+ let cells = ((1.0 - level / FLOOR_DB) * COLS as f64)
+ .round()
+ .clamp(0.0, COLS as f64) as usize;
+
+ let near = |t: f64| (w - t).abs() <= 0.5 * step;
+ let tag = if near(r.peak_w) {
+ '<'
+ } else if near(-r.peak_w) {
+ '>'
+ } else if near(r.edges.0) || near(r.edges.1) {
+ '-'
+ } else {
+ ' '
+ };
+
+ println!(
+ "{:>10.5} {:>9.5} {:>8.2} {tag}{}",
+ w,
+ w / TAU,
+ level,
+ "#".repeat(cells)
+ );
+ }
+ }
+}
+
+#[ignore]
+#[test]
+fn print_chirp_transform() {
+ // Make a little plot similar to the one show in this paper:
+ // https://jmlilly.net/papers/lilly09-itsp-cp.pdf
+ //
+ // The paper uses a beta and gamma we can't quite draw (betas this low are not generally
+ // supported yet), but our outputs are somewhat similar at relevant beta.
+
+ const TAIL_DB: f64 = -40.0;
+ const SPAN: isize = 400;
+ const SD: f64 = 90.0;
+ const ROWS: usize = 40;
+
+ // ρ of the top and bottom rows, the ridge reaching ρ_top at the window edge
+ const RHO_TOP: f64 = 0.10;
+ const RHO_BOT: f64 = 0.002;
+
+ let wav = WaveletSpec::default()
+ .shape(Shape {
+ beta: 3.0,
+ gamma: 3.0,
+ })
+ .max_truncation(TAIL_DB)
+ .bake();
+
+ // ρ_top (ρ_bot/ρ_top)^(r/(ROWS−1))
+ let bank: Vec<(f64, Weights)> = (0..ROWS)
+ .map(|r| {
+ let f = r as f64 / (ROWS - 1) as f64;
+ let bin = wav.at_rho(RHO_TOP * (RHO_BOT / RHO_TOP).powf(f));
+ (bin.velocity(), bin.weights())
+ })
+ .collect();
+
+ // ω(t) = a·t
+ let a = bank[0].0 / SPAN as f64;
+ let x = chirp(a, SD, 0.0);
+
+ print_transform("MORSE", &bank, &x, SPAN, 160, -40.0);
+}
diff --git a/mutate-lib/src/dsp/wavelet/tests/smoke.rs b/mutate-lib/src/dsp/wavelet/tests/smoke.rs
new file mode 100644
index 00000000..4073bf24
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/tests/smoke.rs
@@ -0,0 +1,520 @@
+//! # Smoke Tests
+//!
+//! Tests that fail when some measurable characteristic of the wavelet or the test model is
+//! *hypothetically* bad. Ideally, failures here already show up as failures in the primary
+//! characteristics of interest, actual PSL and actual reassignment precision etc. In practice,
+//! wavelets may outperform what these foundation inspections look at, and these tests are
+//! considered smoke tests that tell us when to look more deeply and where.
+//!
+//! > Fast food is bad for you. Wouldn't you rather wait for healthy food? Unidentified benevolent
+//! > beings are working hard every day to bring us healthy food someday, and if we believe in them
+//! > really hard, in ten more years, they will give healthy food to everyone! If ten years from now,
+//! > the healthy food still isn't here, those to blame will be the non-believers, so today we must
+//! > socially coerce our information spaces to only be filled with believers, those who will wait,
+//! > and we must attack and deny oxygen to the enemies of "free" software, anyone who actually
+//! > writes code or drives forward with proactive action.
+//! >
+//! > - distinguished Redditor u/Wb9VBScxu2uZJHeq2E3W
+
+#![warn(warnings, dead_code, unused_variables)]
+
+use core::f64::consts::{LN_2, PI, TAU};
+
+use super::super::{
+ fmt_e,
+ harness::*,
+ inspect::*,
+ refine,
+ spec::{Shape, WaveletSpec},
+ PEAK_GAIN,
+};
+
+const RATE: f64 = 48_000.0;
+
+#[test]
+fn gamma_sweep() {
+ const QUANTUM: usize = 4;
+ const STEP: f64 = 100.0;
+ const SPAN: isize = 4;
+ /// Worst reassignment bias over the scan, in cents.
+ const BIAS_C: f64 = 1.2;
+ const TAIL_DB: f64 = 60.0;
+
+ println!("\n=== TAP PROFILE vs GAMMA (Q = 2.4) ===");
+ // P² = beta gamma
+ let p = 4.0;
+ for gamma in [1.0f64, 2.0, 3.0, 6.0] {
+ let wav = WaveletSpec::default()
+ .shape(Shape {
+ gamma,
+ beta: p * p / gamma,
+ })
+ .max_load_quantum(QUANTUM)
+ .max_truncation(TAIL_DB)
+ .bake();
+ let bin = wav.at_rho(1000.0 / 8000.0);
+ let w0 = bin.velocity();
+ let wts = bin.weights();
+ let (psi, d) = (wts.psi(), wts.d());
+ let n = psi.len_unfolded();
+
+ // M₁ / M₀
+ let delay = (psi.moment(1) / psi.moment(0)).re;
+
+ // worst over detuning of |R| / ‖ψ‖₁ and of (1200/ln 2)·(R/H)/r
+ let (floor, worst) = (-SPAN..=SPAN).fold((0.0f64, 0.0f64), |acc, k| {
+ let ratio = (k as f64 * STEP / 1200.0).exp2();
+ let (res, dr) = pairing_residual(psi, d, w0, w0 * ratio);
+ (
+ acc.0.max(res / psi.l1()),
+ // (1200 / ln 2) · (R/H) / r
+ acc.1.max((1200.0 / LN_2 * dr / ratio).abs()),
+ )
+ });
+
+ println!(
+ "\ngamma = {gamma:.1} weights {} taps {n} delay = {delay:+.3e} \
+ floor = {} bias = {worst:.3}c",
+ psi.len_folded(),
+ fmt_e(floor),
+ );
+
+ let mags: Vec = psi.mirrored().map(|h| h.norm()).collect();
+ let max = mags.iter().fold(0.0f64, |a, &b| a.max(b));
+ for (j, &v) in mags.iter().enumerate() {
+ println!(
+ "{:>4} {}",
+ j as isize - (n / 2) as isize,
+ "#".repeat((v / max * 40.0).round() as usize)
+ );
+ }
+
+ assert!(worst < BIAS_C, "gamma {gamma} bias {worst:.3}c");
+ }
+}
+
+/// Negative frequency energy of each bin, split into the beat against its own passband and
+/// leakage through the mirror, beside the positive skirt it competes with. If leak+ is larger
+/// than leak-, the stopband is dominated by the skirt, telling us where to prioritize spectral
+/// cleanup work.
+#[test]
+fn wavelet_is_analytic() {
+ const BINS: usize = 6;
+ const WORST: usize = 2;
+
+ const QS: Axis = Axis::Levels(&[3.0, 4.0]);
+ const GAMMAS: Axis = Axis::Levels(&[3.0, 4.0]);
+ const DEEPEST_DB: f64 = -80.0;
+ const FLOORS: Axis = Axis::Step(-40.0, DEEPEST_DB, 10.0);
+ const RHO: Span = Span::Log(0.004, 0.45);
+
+ const GOOD: f64 = 0.95;
+ const EXCESS: f64 = 1e-2;
+
+ let pow_db = |u: f64| 10.0 * u.log10();
+ let amp_db = |u: f64| 20.0 * u.log10();
+ let med = |v: &mut Vec<(f64, f64)>| weighted_quantile(v, 0.5);
+ let mut ledger = Ledger::default();
+
+ println!("\n=== ANALYTICITY ===");
+ println!(" shares of white noise energy ∫|H|², dB, medians over served ρ");
+ println!(" beat is image inside the passband guard, leak− and leak+ outside it");
+ println!(" α is |H(−ω)|/|H(ω)| weighted by |H(ω)|² in band, peak re PEAK_GAIN\n");
+ println!(
+ " {:>4} {:>5} {:>6} {:>8} {:>8} {:>8} {:>8} {:>8} {:>8} {:>7}",
+ "γ", "Q", "floor", "beat", "leak−", "leak+", "α50", "α99", "peak", "beyond"
+ );
+
+ for (wg, gamma) in GAMMAS.levels() {
+ for (wq, q) in QS.levels() {
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(q, gamma))
+ .max_noise_floor(DEEPEST_DB)
+ .bake();
+ let s = wav.shape();
+
+ for (wf, floor) in FLOORS.levels() {
+ let [mut beat, mut neg, mut pos, mut a50, mut a99, mut peak]: [Vec<(f64, f64)>; 6] =
+ Default::default();
+ let mut beyond = 0usize;
+
+ for (wr, [rho]) in survey([RHO], BINS) {
+ // ρ ≤ ρ_fold(floor)
+ if rho > s.fold_ceiling(floor) {
+ beyond += 1;
+ continue;
+ }
+
+ let bin = wav.at_rho(rho).with_noise_floor(floor);
+ let wts = bin.weights();
+ let psi = wts.psi();
+ let mut img = image(psi, bin.velocity());
+
+ beat.push((wr, img.beat));
+ neg.push((wr, img.leak_neg));
+ pos.push((wr, img.leak_pos));
+ a50.push((wr, weighted_quantile(&mut img.alpha, 0.5)));
+ a99.push((wr, weighted_quantile(&mut img.alpha, 0.99)));
+ peak.push((wr, img.peak.1 / PEAK_GAIN));
+
+ // 10^(floor/10)
+ let tol = 10f64.powf(floor / 10.0);
+ let at_w = img.peak.0 / bin.velocity();
+ ledger.record(
+ wg * wq * wf * wr,
+ (img.beat + img.leak_neg) / tol,
+ at!(q, gamma, floor, rho, at_w),
+ );
+ }
+
+ println!(
+ " {gamma:>4.1} {q:>5.1} {floor:>6.0} {:>8.2} {:>8.2} {:>8.2} \
+ {:>8.2} {:>8.2} {:>8.2} {beyond:>7}",
+ pow_db(med(&mut beat)),
+ pow_db(med(&mut neg)),
+ pow_db(med(&mut pos)),
+ amp_db(med(&mut a50)),
+ amp_db(med(&mut a99)),
+ amp_db(med(&mut peak)),
+ );
+ }
+ println!();
+ }
+ }
+
+ ledger.print_worst(WORST);
+ let [good, excess] = ledger.verdict([GOOD, EXCESS]);
+
+ assert!(good > GOOD, "good mass {good:.4}");
+ assert!(excess < EXCESS, "excess mass {excess:.2e}");
+}
+
+/// Whether the filter answers the same at every input phase. Each row drives a steady tone
+/// through the full 2π of carrier phase and demodulates each lane, so the reported number is
+/// the worst relative departure from that lane's phase mean. Zero is phase blind.
+#[test]
+fn response_is_phase_independent() {
+ const Q: f64 = 8.5;
+ const QUANTUM: usize = 4;
+ const TAIL_DB: f64 = -60.0;
+
+ const GATE_DB: f64 = -50.0;
+ const RESOLUTION: f64 = 0.05;
+
+ /// Well above anything the image alone produces in band.
+ const SWING_TOL: f64 = 5e-2;
+
+ const STEP: f64 = 25.0;
+ const SPAN: isize = 6;
+
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(Q, 3.0))
+ .max_load_quantum(QUANTUM)
+ .max_truncation(TAIL_DB)
+ .bake();
+
+ println!("\n=== RESPONSE PHASE DEPENDENCE ===");
+ println!(" detune |H| img ψ psi d t");
+
+ for (fc, fs) in [
+ (2_000.0f64, RATE),
+ (200.0, 3000.0),
+ (250.0, 3000.0),
+ (12_000.0, RATE),
+ ] {
+ let bin = wav.at_rho(fc / fs);
+ let wts = bin.weights();
+ let psi = wts.psi();
+
+ let (n, w0) = (psi.len_unfolded(), bin.velocity());
+ println!(" fc {fc:.0} fs {fs:.0} taps {n} w0 {w0:.6}");
+
+ for k in -SPAN..=SPAN {
+ let cents = k as f64 * STEP;
+ let wd = w0 * (cents / 1200.0).exp2();
+ let h_db = db(psi.dtft(wd).abs()) - db(PEAK_GAIN);
+ if h_db < GATE_DB {
+ continue;
+ }
+
+ let [sp, sd, st] = tone_response(&wts, w0, cents, RESOLUTION);
+ let img = psi.dtft(-wd).abs();
+
+ println!(
+ " {cents:+6.0}c {h_db:>7.1} {:>8.1} {sp:>11.2e} {sd:>11.2e} {st:>11.2e}",
+ db(img) - db(PEAK_GAIN),
+ );
+
+ for (lane, s) in ["psi", "d", "t"].iter().zip([sp, sd, st]) {
+ assert!(
+ s < SWING_TOL,
+ "fc {fc} detune {cents} lane {lane} swing {s:.3e}"
+ );
+ }
+ }
+ }
+}
+
+/// Whether the reported pitch and quadrature move with the carrier phase. Each row sweeps
+/// the full 2π of input phase at `RESOLUTION` and reports the departure from the phase mean,
+/// so a filter that answers the same for every phase reads zero across the board. The swing
+/// is the negative frequency image beating against the signal, so the budget scales with
+/// image over signal rather than being flat.
+#[test]
+fn reassignment_is_phase_independent() {
+ const Q: f64 = 8.5;
+ const QUANTUM: usize = 4;
+ const TAIL_DB: f64 = -60.0;
+
+ const GATE_DB: f64 = -50.0;
+ const RESOLUTION: f64 = 0.05;
+
+ /// Swing the image alone implies, within this factor. Second order in |α|, so tight.
+ const SWING_C: f64 = 1.3;
+
+ const STEP: f64 = 25.0;
+ const SPAN: isize = 6;
+
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(Q, 3.0))
+ .max_load_quantum(QUANTUM)
+ .max_truncation(TAIL_DB)
+ .bake();
+
+ println!("\n=== PHASE DEPENDENCE ===");
+ println!(" detune |H| img ψ img d pred swing ratio");
+
+ for (fc, fs) in [
+ (2_000.0f64, RATE),
+ (200.0, 3000.0),
+ (250.0, 3000.0),
+ (12_000.0, RATE),
+ ] {
+ let bin = wav.at_rho(fc / fs);
+ let wts = bin.weights();
+ let (psi, d) = (wts.psi(), wts.d());
+
+ let (n, w0) = (psi.len_unfolded(), bin.velocity());
+ println!(" fc {fc:.0} fs {fs:.0} taps {n} w0 {w0:.6}");
+
+ for k in -SPAN..=SPAN {
+ let cents = k as f64 * STEP;
+ let wd = w0 * (cents / 1200.0).exp2();
+ let h = psi.dtft(wd).abs();
+ let h_db = 20.0 * (h / PEAK_GAIN).log10();
+ if h_db < GATE_DB {
+ continue;
+ }
+
+ let ((_, swing), (quad, _)) = tone_bias(&wts, w0, cents, RESOLUTION);
+
+ // H_ψ(±ω), H_d(±ω)
+ let (p, p_img) = (psi.dtft(wd), psi.dtft(-wd));
+ let (q, q_img) = (d.dtft(wd), d.dtft(-wd));
+ // α = H_d(−ω)/H_d(ω) − H_ψ(−ω)/H_ψ(ω)
+ let alpha = q_img / q - p_img / p;
+ let pred = 1200.0 / LN_2 * alpha.abs();
+
+ println!(
+ " {cents:+6.0}c {h_db:>7.1} {:>8.1} {:>8.1} {pred:>8.3}c {swing:>8.3}c {:>9.3}",
+ db(p_img.abs()) - db(PEAK_GAIN),
+ db(q_img.abs()) - db(PEAK_GAIN),
+ swing / pred,
+ );
+
+ assert!(
+ swing < SWING_C * pred + 1e-3,
+ "fc {fc} detune {cents} swing {swing:.4}c over {:.4}c",
+ SWING_C * pred + 1e-3
+ );
+ assert!(
+ quad.abs() < 1e-12,
+ "fc {fc} detune {cents} quad mean {quad:.3e}"
+ );
+ }
+ }
+}
+
+/// A real unit tone at the crest reads |W| = 1 even though |H| = 2: the analytic taps see only
+/// the +ω half of the cosine, and the −ω half beats against it by ½|H(−ω)|.
+#[test]
+fn unit_tone_reads_unity() {
+ const EPS: f64 = 1e-6;
+ const BINS: usize = 16;
+ const WORST: usize = 2;
+
+ const QS: Axis = Axis::Levels(&[3.0, 4.25, 6.0]);
+ const GAMMAS: Axis = Axis::Levels(&[3.0, 4.0, 6.0]);
+ const RHO: Span = Span::Log(0.004, 0.45);
+ const TAIL_DB: Span = Span::Lin(-20.0, -100.0);
+
+ const GOOD: f64 = 0.99;
+ const EXCESS: f64 = 5e-3;
+
+ let mut probe = Vec::new();
+ let mut all = Ledger::default();
+
+ println!("\n=== UNIT TONE ===");
+ println!(" good is the weighted share within tolerance, excess the capped overshoot mass\n");
+ println!(" {:>6} {:>6} {:>8} {:>10}", "Q", "γ", "good", "excess");
+
+ for (_, gamma) in GAMMAS.levels() {
+ for (_, q) in QS.levels() {
+ let wav = WaveletSpec::default()
+ .shape(Shape::from_q(q, gamma))
+ .max_truncation(TAIL_DB.end())
+ .bake();
+
+ let mut shape = Ledger::default();
+ for (w, [rho, tail_db]) in survey([RHO, TAIL_DB], BINS) {
+ let bin = wav.at_rho(rho).with_truncation(tail_db);
+ let wts = bin.weights();
+ let psi = wts.psi();
+
+ // ω_peak
+ let Some((wp, _)) =
+ Inspect::new(psi, &mut probe, OVERSAMPLE).peak(bin.velocity(), 0.0, PI)
+ else {
+ shape.record(w, f64::NAN, at!(q, gamma, rho, tail_db));
+ continue;
+ };
+
+ // ½|H(−ω_peak)| + ε
+ let tol = 0.5 * psi.dtft(-wp).abs() + EPS;
+
+ // max over m of | |Ψ(m)| − 1 |
+ let err = (0..8)
+ .map(|m| (wts.project(|k| (wp * k as f64).cos(), m)[0].norm() - 1.0).abs())
+ .fold(0.0f64, f64::max);
+
+ shape.record(w, err / tol, at!(q, gamma, rho, tail_db));
+ }
+
+ println!(
+ " {q:>6.2} {gamma:>6.2} {:>8.4} {:>10.2e}",
+ shape.good(),
+ shape.excess()
+ );
+ all.absorb(shape);
+ }
+ }
+
+ all.print_worst(WORST);
+ let [good, excess] = all.verdict([GOOD, EXCESS]);
+
+ assert!(good > GOOD, "good mass {good:.4}");
+ assert!(excess < EXCESS, "excess mass {excess:.2e}");
+}
+
+/// Peak-normalized constant-Q puts noise gain proportional to ρ: the ψ sum is pinned at
+/// PEAK_GAIN, so the envelope's amplitude scales with ρ and its energy with ρ². Dividing that
+/// back by the ρ⁻¹ taps per period leaves one power of ρ. White noise therefore floors at a
+/// fixed level per bin once ρ is divided out.
+#[test]
+fn noise_gain_tracks_center() {
+ const Q: f64 = 3.0;
+ const QUANTUM: usize = 4;
+ const TAIL_DB: f64 = -100.0;
+
+ // Tap count is an integer, so envelope truncation loses O(1/N) of the energy, worst at
+ // the top of the range. Anchored to split the sweep rather than to any one bin.
+ const NOISE_GAIN: f64 = 1.4105;
+ const TOL: f64 = 2e-3;
+
+ let w = WaveletSpec::default()
+ .shape(Shape::from_q(Q, 3.0))
+ .max_load_quantum(QUANTUM)
+ .max_truncation(TAIL_DB)
+ .bake();
+
+ println!("\n=== NOISE GAIN (Q = {Q}, fs = {RATE}, quantum {QUANTUM}) ===");
+
+ for fc in [500.0f64, 1000.0, 2000.0, 4000.0, 8000.0] {
+ let bin = w.bin(fc, RATE);
+ let wts = bin.weights();
+ let psi = wts.psi();
+
+ let e = psi.energy();
+ let ratio = e / bin.rho();
+
+ println!(
+ " fc {:>6.0} taps {:>5} rho {:.6} energy {:.6} e/rho {:.6} dev {:+.2e}",
+ fc,
+ bin.len_unfolded(),
+ bin.rho(),
+ e,
+ ratio,
+ ratio / NOISE_GAIN - 1.0
+ );
+
+ assert!(
+ (ratio / NOISE_GAIN - 1.0).abs() < TOL,
+ "fc {fc} noise gain {ratio:.6}"
+ );
+ }
+}
+
+/// Smoke test. DC-free and correct peak gain, measured with the linear DTFT so a broken fold
+/// convention can't agree with itself. First thing to look at if the bake goes sideways.
+#[test]
+fn taps_are_conditioned() {
+ // Use a rough tail dB so we can verify conditioning under challenging conditions.
+ const TAIL_DB: f64 = -80.0;
+ const MOMENT_TOL: f64 = 1e-6;
+
+ // NOTE the refinement is explicitly set so that this test doesn't regress whenever the
+ // default moment conditioning is updated.
+ let wav = WaveletSpec::default()
+ .max_truncation(TAIL_DB)
+ .refinement(Some(refine::Refinement::Reach {
+ moments: &[0, 1, 2, 3],
+ jet: &[0, 1, 2, 3],
+ tangent: true,
+ spare: 16,
+ turns: 3.0,
+ }))
+ .bake();
+
+ for (fc, fs) in [(1000.0f64, 8000.0f64), (250.0, 3000.0), (12_000.0, RATE)] {
+ let bin = wav.at_rho(fc / fs);
+ let wts = bin.weights();
+ let (psi, d) = (wts.psi(), wts.d());
+
+ let w0 = bin.velocity();
+
+ let g = psi.dtft(w0).abs();
+ assert!((g - PEAK_GAIN).abs() < 1e-2, "fc {fc} peak gain {g:.6}");
+
+ // Analytic taps: the mirror image is stopband, not signal.
+ let neg = psi.dtft(-w0).abs();
+ assert!(
+ neg < 1e-3 * g,
+ "fc {fc} negative-freq leak {:.2} dB",
+ 20.0 * (neg / g).log10()
+ );
+
+ let dc = psi.dtft(0.0);
+ assert!(dc.abs() < 1e-2 * g, "fc {fc} dc {dc:.3e}");
+
+ // d/ψ reads ω/ω₀, unity at the carrier.
+ let gd = d.dtft(w0).abs();
+ assert!((gd / g - 1.0).abs() < 1e-2, "fc {fc} d/psi {:.6}", gd / g);
+
+ // Σ ν^p · (Re ψ if p even, Im ψ if p odd)
+ let mom = |p: i32| match p % 2 == 0 {
+ true => psi.moment(p).re,
+ false => psi.moment(p).im,
+ };
+
+ // |M_p| / A_p, the share of each moment's scale left uncancelled. H^(p)(0) for p = 2, 3
+ // are the ones the solve nulls that nothing else measures.
+ for p in 0..=3 {
+ let residue = mom(p).abs() / psi.abs_moment(p);
+ println!(" fc {fc:>6.0} M{p} residue {residue:.3e}");
+ assert!(
+ residue < MOMENT_TOL,
+ "fc {fc} moment {p} residue {residue:.3e}"
+ );
+ }
+ }
+}
diff --git a/mutate-lib/src/dsp/wavelet/whatsleft.rs b/mutate-lib/src/dsp/wavelet/whatsleft.rs
new file mode 100644
index 00000000..44807ced
--- /dev/null
+++ b/mutate-lib/src/dsp/wavelet/whatsleft.rs
@@ -0,0 +1,466 @@
+// Copyright 2026 The MuTate Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! # High-Precision, Destruction Tolerant Accumulator
+//!
+//! > When I'm done, half will still remain.
+//! >
+//! > - Ivo Nahak
+//!
+//! Calculating **vanishing** residuals of oscillating functions can provide marvelous opportunities
+//! for transient losses of precision to obliterate the contributions of many whole terms.
+//!
+//! This implementation descended from using a stack array to perform a tree sum as each term is
+//! emitted, so no pre-generation or sorting would be required. Further review lead to the
+//! realization that the stack slots could be used to store compensator terms, retaining more
+//! precision of each intermediate term. The result is similar to a Møller–Knuth two-sum style
+//! bidirectional carry. The benefits for long vanishing sums are demonstrated. Add as you like.
+//! Destructively cancel as you will.
+//!
+//! There has been a lot of convergent evolution over the years:
+//!
+//! - Wolfe (1964) took the first step toward bucket summation.
+//! - Malcolm's (1974) contribution was reducing the number of buckets by associating each with `d`
+//! consecutive exponents.
+//!
+//! Additionally, these contributions were pointed out as "roughly similar" in ways that are likely
+//! to at least inspire improvements if not land on the formalization:
+//!
+//! - Zhu & Hayes, HybridSum (2009) and OnlineExactSum (2010)
+//! - Lange & Rump aaaSum (2022)
+//!
+//! This is a toy implementation used in some tests and does not use SIMD or any kind of fast
+//! routing decisions, and that strongly limits the performance. It does better than Kahan 64-bit
+//! summation while using 32bit operands. If they were fast 32bit operands, it might actually be
+//! worth it!
+
+// NOTE If the SIMD or generalized compensator structure get done, it will be time for this to
+// become a published crate. Numerical integrations have to contend with finer resolution vs higher
+// error all the time, and residual sums are just one pathological case.
+
+// NEXT Assemble some pathological test cases to at least think about what functions this can't be
+// used to sum, especially ones where the other methods are better.
+
+// NEXT The next architecture improvements will all flow along a set of predictable paths:
+//
+// - Scalar insertion of summands will pre-split and pipeline with rolling accounting work
+// - Space time tradeoff with an error track on the magnitude of the worst rounding that was forced
+// by running out of bins. This is the user's engineering knob. People doing big sums can
+// tolerate leakage in low bins as long as the maximum error scale is known
+// - Pre-split insertions may coalesce via pre-calculated routing
+// - Opportunistic SIMD drain steps
+// - More space, more latency hiding, fewer stalls, another engineering knob expressed as a simple
+// const generic and an error check in the return value.
+
+// NEXT Complex support as some kind of adapter trait for n-floats structures as long as they are
+// commutative and associative, basically as long as we can treat n-floats as n-sums.
+// MAYBE Peek sum vs consuming finalizer sum. Depends on if the stores can be skipped efficiently
+// and if registers pressure / shuffling is different for consume compared to peek. My bet is that
+// SIMD will later want a consume method that uses the fast path while peek has to avoid destroying
+// any compensators. Peek is extremely useful for prefix summing.
+// NEXT Multithreaded cases would need a way to return one compensator-residual set so that
+// intermediate sums retain acquired precision across boundaries. In the single threaded case, a
+// by-ref accumulator is the best choice.
+
+use std::ops::{Add, Sub};
+
+use aligned::{Aligned, A64};
+use num_traits::Float;
+
+/// A bank of Kahan accumulators, one per magnitude band.
+///
+/// Incoming values route to the band matching their magnitude. When a slot's value leaves its band
+/// it is carried into the band it now belongs to. That carry is what keeps each accumulator small
+/// relative to its own compensator, alleviating the worst case magnitude differences that can
+/// frustrate simple Kahan summation.
+#[derive(Clone, Copy)]
+pub struct Accumulator {
+ slots: Aligned,
+ min_exp: i32,
+}
+
+impl Default for Accumulator {
+ fn default() -> Self {
+ let (_, min_exp, _) = F::min_positive_value().integer_decode();
+ Self {
+ slots: Aligned([(F::zero(), F::zero()); N]),
+ min_exp: min_exp as i32,
+ }
+ }
+}
+
+// Type inference anchor for the default band count.
+impl Accumulator {
+ pub fn default() -> Self {
+ ::default()
+ }
+}
+
+fn two_sum(a: F, b: F) -> (F, F) {
+ let s = a + b;
+ let bb = s - a;
+ (s, (a - (s - bb)) + (b - bb))
+}
+
+impl