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 Accumulator { + #[inline(always)] + fn bin(&self, x: F) -> usize { + let (_, e, _) = x.integer_decode(); + (((e as i32 - self.min_exp) / 8) as usize).min(N - 1) + } + + fn insert(&mut self, x: F) { + let mut pending = x; + while !pending.is_zero() { + let i = self.bin(pending); + let (v, c) = self.slots[i]; + + let (v2, e) = two_sum(v, pending); + let (c2, _third_order) = two_sum(c, e); + + if v2.is_zero() || self.bin(v2) == i { + self.slots[i] = (v2, c2); + return; + } + + self.slots[i] = (F::zero(), F::zero()); + if !c2.is_zero() { + self.insert(c2); + } + pending = v2; + } + } + + pub fn add(&mut self, value: F) { + self.insert(value); + } + + pub fn sub(&mut self, value: F) { + self.insert(-value); + } + + /// Compensated fold from the smallest band upward, taking each slot's compensation + /// before its value so the single unavoidable rounding lands once, at the top. + pub fn sum(&self) -> F { + let (v, c) = self + .slots + .iter() + .fold((F::zero(), F::zero()), |(acc, comp), &(v, c)| { + let (t1, e1) = two_sum(acc, c); + let (t2, e2) = two_sum(t1, v); + (t2, comp + e1 + e2) + }); + v + c + } +} + +/// A stand-in **uncompensated** accumulator with the same interface but fully **uncompensated** +/// implementation. To use, just shadow the normal type in the scope under scrutiny and then +/// compare the results. +/// +/// ```ignore +/// use whatsleft::NaiveSum as Accumulator; +/// +/// // Quacks like a duck. Is not a duck. +/// let sum = Accumulator::new(); +/// +/// ``` +/// +/// Comment or remove the shadow to compare results and decide if the compensation is doing real +/// work for the situation at hand. This manner of testing is crude and not a substitute for error +/// propagation analysis. If downstream usage or *in situ* input will exposee or magnify lost +/// precision from the uncompensated sum, eyeballing local testing may lead to a false negative. +#[derive(Clone, Copy)] +pub struct NaiveSum { + total: F, +} + +impl Default for NaiveSum { + fn default() -> Self { + Self { total: F::zero() } + } +} + +impl NaiveSum { + pub fn default() -> Self { + ::default() + } +} + +impl NaiveSum { + #[inline(always)] + fn insert(&mut self, x: F) { + self.total = self.total + x; + } + + #[inline(always)] + pub fn add(&mut self, value: F) { + self.insert(value); + } + + #[inline(always)] + pub fn sub(&mut self, value: F) { + self.insert(-value); + } + + #[inline(always)] + pub fn sum(&self) -> F { + self.total + } +} + +#[cfg(test)] +mod test { + use super::*; + + /// Neumaier's improvement over Kahan: the correction is chosen by comparing magnitudes, so it + /// stays correct when the incoming term dominates the running sum. Its weakness is that `c` + /// is itself a plain accumulator — corrections spanning many magnitudes fall off its bottom. + fn neumaier_step(x: F, v: &mut F, c: &mut F) { + let t = *v + x; + *c = *c + + if v.abs() >= x.abs() { + (*v - t) + x + } else { + (x - t) + *v + }; + *v = t; + } + + #[test] + fn all_zeroes() { + let mut a: Accumulator = Accumulator::default(); + for v in vec![0.0_f32; 100] { + a.add(v); + } + assert_eq!(a.sum(), 0.0); + } + + #[test] + fn beats_naive() { + // small amplitude phasor, rotated through some cycles. Exactly predictable residual. + // Accumulator should be bracketed by expected and naive results. + + let cycles = 119_usize; + let samples_per_cycle = 320001_usize; // odd, not a power of two + let n = cycles * samples_per_cycle; + + let amplitude = 1.0e-2_f64; + let theta = 2.0 * std::f64::consts::PI / samples_per_cycle as f64; + let (sin_t, cos_t) = theta.sin_cos(); + + // unit phasor, rotated in place each step + let (mut re, mut im) = (1.0_f64, 0.0_f64); + + let mut accum = Accumulator::::default(); + let mut naive = NaiveSum::::default(); + + // Go ahead and destroy the precision scales + accum.add(77.0); + naive.add(77.0); + + for _ in 0..n { + let sample = (amplitude * im) as f32; + accum.add(sample); + naive.add(sample); + + let next_re = re * cos_t - im * sin_t; + let next_im = re * sin_t + im * cos_t; + re = next_re; + im = next_im; + + // Newton step to keep the phasor from spiraling. + let mag_sq = re * re + im * im; + let k = 1.5 - 0.5 * mag_sq; + re *= k; + im *= k; + } + + // let expected = 1.0e4; + let expected = 77.0; + let accum_result = accum.sum(); + let naive_result = naive.sum(); + + let accum_err = (accum_result as f64 - expected).abs(); + let naive_err = (naive_result as f64 - expected).abs(); + + // Several orders better on the accumulator + println!( + "expected: {}, accumulator error: {:+0.4e}, naive error: {:+0.4e}", + expected, accum_err, naive_err + ); + + assert!( + accum_err < naive_err, + "accum ({accum_result:+0.4e}, err {accum_err:+0.4e}) should beat naive ({naive_result:+0.4e}, err {naive_err:+0.4e})" + ); + assert!( + (naive_err > 1e-7), + "naive was unexpectedly exact — test isn't stressing accumulation" + ); + } + + #[test] + fn beats_kahan() { + // Sum a chirp, then sum the negation. Result should be zero, but Kahan alone can't let you + // do that. + let n = 4_000_000_usize; + let theta = 2.0 * std::f64::consts::PI / 977.0; // odd period, no exact cancellation + let log_start = 1.0e18_f64.ln(); + let log_end = 1.0e-18_f64.ln(); + + // The offset's job is to upset the residual at any given time and then become the residual + // at the end. + let offset = 0.5_f32; + + let sample = |i: usize| -> f32 { + let t = i as f64 / (n - 1) as f64; + let amp = (log_start + (log_end - log_start) * t).exp(); + (amp * (i as f64 * theta).sin()) as f32 + }; + + let mut kahan32_v = offset; + let mut kahan32_c = 0.0_f32; + let mut kahan64_v = offset as f64; + let mut kahan64_c = 0.0_f64; + let mut accum = Accumulator::::default(); + accum.add(offset); + + fn kahan_step(x: F, v: &mut F, c: &mut F) + where + F: Copy + Add + Sub, + { + let y = x - *c; + let sum = *v + y; + *c = (sum - *v) - y; + *v = sum; + } + + for i in 0..n { + let x = sample(i); + kahan_step(x, &mut kahan32_v, &mut kahan32_c); + kahan_step(x as f64, &mut kahan64_v, &mut kahan64_c); + accum.add(x); + } + for i in (0..n).rev() { + let x = -sample(i); + kahan_step(x, &mut kahan32_v, &mut kahan32_c); + kahan_step(x as f64, &mut kahan64_v, &mut kahan64_c); + accum.add(x); + } + + let expected = offset as f64; + let kahan32_err = (kahan32_v as f64 - expected).abs(); + let kahan64_err = (kahan64_v - expected).abs(); + let accum_err = (accum.sum() as f64 - expected).abs(); + + println!( + "expected: {expected}, kahan32 error: {kahan32_err:+0.16e}, kahan64 error: {kahan64_err:+0.16e}, accumulator error: {accum_err:+0.16e}" + ); + + assert!( + accum_err < kahan32_err, + "accumulator ({accum_err:+0.4e}) should beat kahan32 ({kahan32_err:+0.4e})" + ); + } + + #[test] + fn smoke_test_f64() { + let mut a: Accumulator = Accumulator::default(); + for _ in 0..16_000_000 { + a.add(1e-6f64); + } + let result = a.sum(); + + // NOTE didn't think too long about this one, but the rounding may have been in our favor. + // Should remain so on any platform compliant with the same floating point spec. + assert!( + (result - 16.0).abs() < f64::MIN_POSITIVE, + "f64 sum was not sixteen: {}", + result + ); + } + + #[test] + fn meets_neumaier_on_uniform_terms() { + // Uniform small terms into a growing sum: the case Neumaier handles essentially exactly in + // f32. We only need to confirm we are not worse. + let n = 1_000_000_usize; + let x = 1.0e-6_f32; + + let mut neumaier_v = 0.0_f32; + let mut neumaier_c = 0.0_f32; + let mut accum = Accumulator::::default(); + + for _ in 0..n { + neumaier_step(x, &mut neumaier_v, &mut neumaier_c); + accum.add(x); + } + + let expected = n as f64 * x as f64; + let neumaier_err = ((neumaier_v + neumaier_c) as f64 - expected).abs(); + let accum_err = (accum.sum() as f64 - expected).abs(); + + println!( + "expected: {expected}, neumaier error: {neumaier_err:+0.4e}, accumulator error: {accum_err:+0.4e}" + ); + + assert!( + accum_err <= neumaier_err, + "accumulator ({accum_err:+0.4e}) should match or beat neumaier ({neumaier_err:+0.4e})" + ); + } + + #[test] + fn beats_neumaier() { + // Stress the single-compensator assumption directly. The chirp sweeps 36 decades, so the + // per-step corrections themselves span a range no single f32 can hold: early corrections + // near 1e11 pin the exponent of `c` and every later correction rounds straight out of it. + // The anchor offset survives as the whole answer after cancellation. + let n = 4_000_000_usize; + let theta = 2.0 * std::f64::consts::PI / 977.0; + let log_start = 1.0e18_f64.ln(); + let log_end = 1.0e-18_f64.ln(); + + let offset = 0.5_f32; + + let sample = |i: usize| -> f32 { + let t = i as f64 / (n - 1) as f64; + let amp = (log_start + (log_end - log_start) * t).exp(); + (amp * (i as f64 * theta).sin()) as f32 + }; + + let mut neumaier_v = offset; + let mut neumaier_c = 0.0_f32; + let mut accum = Accumulator::::default(); + accum.add(offset); + + for i in 0..n { + let x = sample(i); + neumaier_step(x, &mut neumaier_v, &mut neumaier_c); + accum.add(x); + } + for i in (0..n).rev() { + let x = -sample(i); + neumaier_step(x, &mut neumaier_v, &mut neumaier_c); + accum.add(x); + } + + let expected = offset as f64; + let neumaier_err = ((neumaier_v + neumaier_c) as f64 - expected).abs(); + let accum_err = (accum.sum() as f64 - expected).abs(); + + println!( + "expected: {expected}, neumaier error: {neumaier_err:+0.16e}, accumulator error: {accum_err:+0.16e}" + ); + + assert!( + neumaier_err > 1e-7, + "neumaier was unexpectedly exact — test isn't stressing the compensator" + ); + assert!( + accum_err < neumaier_err, + "accumulator ({accum_err:+0.4e}) should beat neumaier ({neumaier_err:+0.4e})" + ); + } +} diff --git a/mutate-lib/src/dsp/window.rs b/mutate-lib/src/dsp/window.rs index bcd2837c..56c86a3b 100644 --- a/mutate-lib/src/dsp/window.rs +++ b/mutate-lib/src/dsp/window.rs @@ -3,7 +3,11 @@ //! # Window Functions //! -//! This module contains window functions used in many filters, especially DFTs. +//! > Seeing is believing so you better change your specs +//! > +//! > - misattributed +//! +//! This module contains window functions for use in many filters. use std::f64::consts::{PI as PI64, TAU as TAU64}; @@ -60,7 +64,9 @@ pub enum WindowFunction { /// window length, this window offers the engineer maximum control and performance at every goal /// except possibly handling extremely high noise at extremely distant points, which can be /// readily suppressed with other simple zero-delay filters. - DolphChebyshev { attenuation_db: f64 }, + DolphChebyshev { + attenuation_db: f64, + }, // NEXT Kaiser, another tunable window with slightly better noise decay at extreme pitch // differences. This can save an un-filtered DFT from registering a sudden super-loud pitch at // an unexpected, distant frequency. @@ -70,9 +76,12 @@ pub enum WindowFunction { // Paired with another filter to suppress the side lobe growth, this may offer a more precise // main lobe. Parameterized to 1, it *is* the Dolph-Chebyshev window. // Ultraspherical, + Bohman, /// A literal window for pre-calculated weights or just any obtained from another method. This /// variant exists to enable using hardcoded windows in the same interface. - Literal { weights: &'static [f32] }, + Literal { + weights: &'static [f32], + }, } impl WindowFunction { @@ -86,6 +95,7 @@ impl WindowFunction { Self::DolphChebyshev { attenuation_db } => { dolph_chebyshev_window(size, *attenuation_db) } + Self::Bohman => bin_weights(&bohman, size), Self::Literal { weights } => weights.iter().map(|w| *w as f64).collect(), } } @@ -125,6 +135,7 @@ impl WindowFunction { // MAYBE COLA values for Dolph Chebyshev need some experimental tuning. Higher // attenuation was said to demand more overlap. Workbench! Self::DolphChebyshev { attenuation_db } => (length as f64 / 4.0).ceil() as u32, + Self::Bohman => (length as f64 / 4.0).ceil() as u32, Self::Literal { weights } => (length as f64 / 4.0).ceil() as u32, } } @@ -142,6 +153,7 @@ impl WindowFunction { Self::Hamming => 1.0, Self::DolphChebyshev { attenuation_db } => 1.0, Self::Literal { weights } => 1.0, + Self::Bohman => 1.0, } } @@ -155,6 +167,7 @@ impl WindowFunction { Self::Hamming => 1.0, Self::DolphChebyshev { attenuation_db } => 1.0, Self::Literal { weights } => 1.0, + Self::Bohman => 1.0, } } } @@ -168,6 +181,7 @@ impl std::fmt::Display for WindowFunction { Self::Hamming => "Hamming", Self::DolphChebyshev { attenuation_db } => "Dolph-Chebyshev", Self::Literal { weights } => "Literal", + Self::Bohman => "Bohman", }; write!(f, "{name}") } @@ -198,6 +212,21 @@ fn bartlett(x: f64) -> f64 { } } +fn bohman(x: f64) -> f64 { + // All other windows are supported over [0.0, 1.0]. We are going to use the actual half-window + // definition in practice, so this maps over. + half_bohman(x * 2.0 - 1.0) +} + +/// `x` is in [-1.0, 1.0] with 0.0 to either -1.0 or 1.0 being a symmetric single cosine half +/// period, mapped from unity to zero. +fn half_bohman(x: f64) -> f64 { + let x = x.abs(); + let t = std::f64::consts::PI * x; + let (s, c) = t.sin_cos(); + (1.0 - x) * c + s * core::f64::consts::FRAC_1_PI +} + // Our integration samples really close to both endpoints, but technically we're supposed to reach a // specific toe value. Anyway. Better than boxcar. fn hamming(x: f64) -> f64 { @@ -206,8 +235,8 @@ fn hamming(x: f64) -> f64 { A0 - (1.0 - A0) * (2.0 * PI64 * x).cos() } -/// Integrates discrete bin weights given a window_fn. Will automatically normalize windows where -/// normalization in the window_fn is hard. +/// Integrates (first moment only) discrete bin weights given a `window_fn`. Will automatically +/// normalize windows where normalization in the `window_fn` is hard. pub fn bin_weights(window_fn: &impl Fn(f64) -> f64, bins: usize) -> Vec { #[cfg(debug_assertions)] let samples_per_bin = 1; @@ -227,16 +256,10 @@ pub fn bin_weights(window_fn: &impl Fn(f64) -> f64, bins: usize) -> Vec { } weights.push(sum / samples_per_bin as f64); } - if !weights.iter().find(|x| **x == 1.0).is_some() { - let max = weights.iter().fold(0.0f64, |max, x| max.max(*x)); - let norm = 1.0 / max; - weights.iter_mut().for_each(|x| { - *x = *x * norm; - }); - weights - } else { - weights - } + let max = weights.iter().fold(f64::NEG_INFINITY, |max, x| max.max(*x)); + let norm = 1.0 / max; + weights.iter_mut().for_each(|x| *x *= norm); + weights } // # The Dolph-Chebyshev Window @@ -474,6 +497,15 @@ mod test { // printing and everything could be checked via macro, but make printing vs not printing easy to // toggle. The workbench is the best place for real testing. + #[test] + fn test_window_function_bohman() { + let weights = bin_weights(&(bohman as fn(f64) -> f64), 25); + // weights.iter().enumerate().for_each(|(i, b)| { + // println!("Bohman: {:3}: {:0.8}", i, b); + // }); + // assert!(weights.iter().all(|b| *b >= 0.0 && *b <= 1.0)); + } + #[test] fn test_window_function_hamming() { let weights = bin_weights(&(hamming as fn(f64) -> f64), 25); diff --git a/mutate-lib/tests/dispatch.rs b/mutate-lib/tests/dispatch.rs index 07832bcf..f6e2e8e8 100644 --- a/mutate-lib/tests/dispatch.rs +++ b/mutate-lib/tests/dispatch.rs @@ -19,7 +19,7 @@ fn dispatch_increment_read_back() { )] pub struct IncrementPipeline; - with_context!(|device, _instance| { + with_context!(|_instance, device| { // NEXT any test with dispatch can re-use this kind of initialization let queue = device .queues diff --git a/mutate-visualizer/assets/shaders/audio/cwt.reflection.json b/mutate-visualizer/assets/shaders/audio/cwt.reflection.json new file mode 100644 index 00000000..9facfad0 --- /dev/null +++ b/mutate-visualizer/assets/shaders/audio/cwt.reflection.json @@ -0,0 +1,105 @@ +{ + "parameters": [ + { + "name": "pc", + "binding": {"kind": "pushConstantBuffer", "index": 0}, + "type": { + "kind": "constantBuffer", + "elementType": { + "kind": "struct", + "name": "PushConstants", + "fields": [ + { + "name": "input_base", + "type": { + "kind": "scalar", + "scalarType": "uint64" + }, + "binding": {"kind": "uniform", "offset": 0, "size": 8, "elementStride": 0} + }, + { + "name": "static_base", + "type": { + "kind": "scalar", + "scalarType": "uint64" + }, + "binding": {"kind": "uniform", "offset": 8, "size": 8, "elementStride": 0} + }, + { + "name": "output_base", + "type": { + "kind": "scalar", + "scalarType": "uint64" + }, + "binding": {"kind": "uniform", "offset": 16, "size": 8, "elementStride": 0} + } + ] + }, + "containerVarLayout": { + "binding": {"kind": "pushConstantBuffer", "index": 0} + }, + "elementVarLayout": { + "type": { + "kind": "struct", + "name": "PushConstants", + "fields": [ + { + "name": "input_base", + "type": { + "kind": "scalar", + "scalarType": "uint64" + }, + "binding": {"kind": "uniform", "offset": 0, "size": 8, "elementStride": 0} + }, + { + "name": "static_base", + "type": { + "kind": "scalar", + "scalarType": "uint64" + }, + "binding": {"kind": "uniform", "offset": 8, "size": 8, "elementStride": 0} + }, + { + "name": "output_base", + "type": { + "kind": "scalar", + "scalarType": "uint64" + }, + "binding": {"kind": "uniform", "offset": 16, "size": 8, "elementStride": 0} + } + ] + }, + "binding": {"kind": "uniform", "offset": 0, "size": 24, "elementStride": 0} + } + } + } + ], + "entryPoints": [ + { + "name": "main", + "stage": "compute", + "parameters": [ + { + "name": "tid", + "semanticName": "SV_DISPATCHTHREADID", + "type": { + "kind": "vector", + "elementCount": 3, + "elementType": { + "kind": "scalar", + "scalarType": "uint32" + } + } + } + ], + "threadGroupSize": [8, 1, 1], + "bindings": [ + { + "name": "pc", + "binding": {"kind": "pushConstantBuffer", "index": 0} + } + ] + } + ], + "bindlessSpaceIndex": 0 +} diff --git a/mutate-visualizer/assets/shaders/audio/cwt.xx3h b/mutate-visualizer/assets/shaders/audio/cwt.xx3h new file mode 100644 index 00000000..42cedeb9 --- /dev/null +++ b/mutate-visualizer/assets/shaders/audio/cwt.xx3h @@ -0,0 +1 @@ +e6adcffcd37b919c diff --git a/mutate-visualizer/assets/shaders/audio/downsample.reflection.json b/mutate-visualizer/assets/shaders/audio/downsample.reflection.json index ae24177a..3ee78a04 100644 --- a/mutate-visualizer/assets/shaders/audio/downsample.reflection.json +++ b/mutate-visualizer/assets/shaders/audio/downsample.reflection.json @@ -10,51 +10,75 @@ "name": "PushConstants", "fields": [ { - "name": "static_base", + "name": "input_base", "type": { "kind": "scalar", "scalarType": "uint64" }, "binding": {"kind": "uniform", "offset": 0, "size": 8, "elementStride": 0} }, + { + "name": "static_base", + "type": { + "kind": "scalar", + "scalarType": "uint64" + }, + "binding": {"kind": "uniform", "offset": 8, "size": 8, "elementStride": 0} + }, + { + "name": "input_stride", + "type": { + "kind": "scalar", + "scalarType": "uint32" + }, + "binding": {"kind": "uniform", "offset": 16, "size": 4, "elementStride": 0} + }, + { + "name": "input_mask", + "type": { + "kind": "scalar", + "scalarType": "uint32" + }, + "binding": {"kind": "uniform", "offset": 20, "size": 4, "elementStride": 0} + }, { "name": "first_window_center", "type": { "kind": "array", - "elementCount": 3, + "elementCount": 4, "elementType": { "kind": "scalar", "scalarType": "uint32" }, "uniformStride": 4 }, - "binding": {"kind": "uniform", "offset": 8, "size": 12, "elementStride": 4} + "binding": {"kind": "uniform", "offset": 24, "size": 16, "elementStride": 4} }, { "name": "first_output_slot", "type": { "kind": "array", - "elementCount": 3, + "elementCount": 4, "elementType": { "kind": "scalar", "scalarType": "uint32" }, "uniformStride": 4 }, - "binding": {"kind": "uniform", "offset": 20, "size": 12, "elementStride": 4} + "binding": {"kind": "uniform", "offset": 40, "size": 16, "elementStride": 4} }, { "name": "output_count", "type": { "kind": "array", - "elementCount": 3, + "elementCount": 4, "elementType": { "kind": "scalar", "scalarType": "uint32" }, "uniformStride": 4 }, - "binding": {"kind": "uniform", "offset": 32, "size": 12, "elementStride": 4} + "binding": {"kind": "uniform", "offset": 56, "size": 16, "elementStride": 4} } ] }, @@ -67,55 +91,79 @@ "name": "PushConstants", "fields": [ { - "name": "static_base", + "name": "input_base", "type": { "kind": "scalar", "scalarType": "uint64" }, "binding": {"kind": "uniform", "offset": 0, "size": 8, "elementStride": 0} }, + { + "name": "static_base", + "type": { + "kind": "scalar", + "scalarType": "uint64" + }, + "binding": {"kind": "uniform", "offset": 8, "size": 8, "elementStride": 0} + }, + { + "name": "input_stride", + "type": { + "kind": "scalar", + "scalarType": "uint32" + }, + "binding": {"kind": "uniform", "offset": 16, "size": 4, "elementStride": 0} + }, + { + "name": "input_mask", + "type": { + "kind": "scalar", + "scalarType": "uint32" + }, + "binding": {"kind": "uniform", "offset": 20, "size": 4, "elementStride": 0} + }, { "name": "first_window_center", "type": { "kind": "array", - "elementCount": 3, + "elementCount": 4, "elementType": { "kind": "scalar", "scalarType": "uint32" }, "uniformStride": 4 }, - "binding": {"kind": "uniform", "offset": 8, "size": 12, "elementStride": 4} + "binding": {"kind": "uniform", "offset": 24, "size": 16, "elementStride": 4} }, { "name": "first_output_slot", "type": { "kind": "array", - "elementCount": 3, + "elementCount": 4, "elementType": { "kind": "scalar", "scalarType": "uint32" }, "uniformStride": 4 }, - "binding": {"kind": "uniform", "offset": 20, "size": 12, "elementStride": 4} + "binding": {"kind": "uniform", "offset": 40, "size": 16, "elementStride": 4} }, { "name": "output_count", "type": { "kind": "array", - "elementCount": 3, + "elementCount": 4, "elementType": { "kind": "scalar", "scalarType": "uint32" }, "uniformStride": 4 }, - "binding": {"kind": "uniform", "offset": 32, "size": 12, "elementStride": 4} + "binding": {"kind": "uniform", "offset": 56, "size": 16, "elementStride": 4} } ] }, - "binding": {"kind": "uniform", "offset": 0, "size": 44, "elementStride": 0} + "binding": {"kind": "uniform", "offset": 0, "size": 72, "elementStride": 0} } } } @@ -150,7 +198,7 @@ } } ], - "threadGroupSize": [32, 8, 1], + "threadGroupSize": [32, 2, 1], "bindings": [ { "name": "pc", diff --git a/mutate-visualizer/assets/shaders/audio/downsample.xx3h b/mutate-visualizer/assets/shaders/audio/downsample.xx3h index 272e24fc..0b959710 100644 --- a/mutate-visualizer/assets/shaders/audio/downsample.xx3h +++ b/mutate-visualizer/assets/shaders/audio/downsample.xx3h @@ -1 +1 @@ -e03847e9b5a0ad61 +928da1d3a8025b4d diff --git a/mutate-visualizer/assets/shaders/audio/spectrum.reflection.json b/mutate-visualizer/assets/shaders/audio/spectrum.reflection.json new file mode 100644 index 00000000..1c910876 --- /dev/null +++ b/mutate-visualizer/assets/shaders/audio/spectrum.reflection.json @@ -0,0 +1,30 @@ +{ + "parameters": [ + + ], + "entryPoints": [ + { + "name": "main", + "stage": "compute", + "parameters": [ + { + "name": "tid", + "semanticName": "SV_DISPATCHTHREADID", + "type": { + "kind": "vector", + "elementCount": 3, + "elementType": { + "kind": "scalar", + "scalarType": "uint32" + } + } + } + ], + "threadGroupSize": [1, 1, 1], + "bindings": [ + + ] + } + ], + "bindlessSpaceIndex": 0 +} diff --git a/mutate-visualizer/assets/shaders/audio/spectrum.xx3h b/mutate-visualizer/assets/shaders/audio/spectrum.xx3h new file mode 100644 index 00000000..ae3cb2c8 --- /dev/null +++ b/mutate-visualizer/assets/shaders/audio/spectrum.xx3h @@ -0,0 +1 @@ +8e2adcd80cfa9e5c diff --git a/mutate-visualizer/shaders/audio/cwt.slang b/mutate-visualizer/shaders/audio/cwt.slang new file mode 100644 index 00000000..a31a73c8 --- /dev/null +++ b/mutate-visualizer/shaders/audio/cwt.slang @@ -0,0 +1,61 @@ +// Copyright 2026 The MuTate Contributors +// SPDX-License-Identifier: MIT OR Apache-2.0 + +// See the cwt.rs for more details. Field descriptions in the Rust code are +// authoritative. + +struct PushConstants { + // Device address of input data, including the output header state. + uint64_t input_base; + // Device address of static data, such as configs, wavelet table, bin table + // etc. Header is a Config and may point to an Output struct describing + uint64_t static_base; + // Device address of output data and any dynamic state. Read information is + // contained in the Output in the static allocation. + uint64_t output_base; +} + +[[vk::push_constant]] +ConstantBuffer pc; + +static const uint LANES = 32; +[WaveSize(LANES)] +[numthreads(8, 1, 1)] +void main(uint3 tid : SV_DispatchThreadID) { + +// Compile-time: L lanes/window, T = pairs/lane, P hops in flight, U = 4 +// +// - warp = G = 32/L groups +// - group g owns hops [hbase + g*P, +P) +// +// lane l within group owns pairs [l*T, l*T + T) +// + +// uint kbase = lane_in_group * T; // this lane's tap slice +// uint c0 = center_of(hbase + g*P) + kbase; // swizzled word coords + +// float4 acc[P]; // (re_psi, im_psi, re_tpsi, im_tpsi) + +// for (uint kp = 0; kp < T; kp += U) { +// // single-buffered: 64 MADs of cover below +// float4 w[U] = load4x(wbase + (((kbase + kp) & kmask) << 4)); + +// [unroll] for (uint p = 0; p < P; ++p) { +// float4 fwd = lds_load4(c0 + p*H + kp); +// float4 rev = lds_load4_rev(c0 + p*H - kp - (U-1) - 2*kbase); + +// [unroll] for (uint u = 0; u < U; ++u) { +// float s = fwd[u] + rev[U-1-u]; +// float d = fwd[u] - rev[U-1-u]; +// acc[p].x = mad(s, w[u].x, acc[p].x); +// acc[p].y = mad(d, w[u].y, acc[p].y); +// acc[p].z = mad(d, w[u].z, acc[p].z); +// acc[p].w = mad(s, w[u].w, acc[p].w); +// } +// } +// } + +// epilogue: log2(L) butterfly reduce acc[p] within group, lane 0 emits P outputs, +// then rotate c0 forward by G*P*H and repeat. + +} diff --git a/mutate-visualizer/shaders/audio/downsample.slang b/mutate-visualizer/shaders/audio/downsample.slang index fe48c9f1..52f8bced 100644 --- a/mutate-visualizer/shaders/audio/downsample.slang +++ b/mutate-visualizer/shaders/audio/downsample.slang @@ -4,47 +4,47 @@ // See the downsample.rs for more details. Field descriptions in the Rust code // are authoritative. -// LIES ⚠️ Same static/dynamic sub-allocator fiction as dft.slang. Offsets are +// LIES ⚠️ Same static/dynamic sub-allocator fiction as cwt.slang. Offsets are // host-aligned for their target type and add directly to a device address. // NOTE 🤖 Human designed and then re-generated. The scheme takes advantage of // a lot of symmetry. The lane-filter geometry was intentionally designed to -// basically let most cards complete the downsample in a few cycles without any -// tails. Lanes have approximately level work per output sample. The log index -// coincidences were found by the LLM and left to be exploited. Will clean up -// the comments later. - +// basically let most devices complete the downsample in a few cycles without +// any tails. Lanes have approximately level work per output sample. The log +// index coincidences were found by the LLM and left to be exploited. +// // Symmetric FIR, folded: a filter of L taps costs (L+1)/2 multiply-adds. Tap // counts are chosen so that cost, divided across the lanes cooperating on one // output, is the same at every level: // -// level decimation taps folds lanes/output folds/lane outputs/warp -// ──────────────────────────────────────────────────────────────────────── -// 0 2x 25 13 1 13 32 -// 1 4x 49 25 2 13 16 -// 2 8x 97 49 4 13 8 +// level decimation taps pairs lanes/output pairs/lane outputs/group +// ----- ---------- ---- ----- ------------ ---------- ------------- +// 0 2x 21 10 2 5 16 +// 1 4x 41 20 4 5 8 +// 2 8x 81 40 8 5 4 +// 3 16x 161 80 16 5 2 // -// Every lane in the dispatch runs the same 13-iteration loop. Twelve of those -// iterations are unconditionally a folded tap pair; only the thirteenth is -// partial, and it belongs to the lane holding the unpaired center tap. +// Every lane in the dispatch runs the same 5-iteration loop, then cooperating +// lanes reduce to a single lane, which folds in the center tap. radius is +// 10/20/40/80 and lanes_per_output is 2/4/8/16, so the fold divides exactly: +// no masking, and the center always falls to slice zero. // -// A workgroup is WARPS * LANES = 256 threads and emits 256 / lanes_per_output -// outputs -- 256, 128, or 64 -- which is exactly the yield of 512 input samples -// at that level. So workgroup g covers input span [g*512, (g+1)*512) at every -// level, and one rectangular grid serves all three. +// Only one warp per workgroup to give the scheduler flexibility. Levels +// advance independently. The grid is rectangular for occupancy: its width +// covers the hungriest level, and shallower levels retire their tail +// workgroups at the guard. At the tick sizing every level wants the same +// width, so the rectangle is exactly full. +// +// lanes_per_output must stay <= LANES. Above that the reduction crosses the +// wave and WaveShuffle no longer reaches. static const uint LANES = 32; -static const uint WARPS = 8; -static const uint LEVELS = 3; +static const uint LEVELS = 4; -/// Folded multiply-adds per lane. Uniform across levels by construction. -static const uint FOLDS_PER_LANE = 13; +/// Folded multiply-adds per lane, excluding the center tap. +static const uint PAIRS_PER_LANE = 5; struct Config { - uint64_t input_base; uint64_t output_base; - - /// -> RingView[channels]. Indexed by channel. - uint input_views_offset; /// -> RingView[LEVELS * channels]. Indexed by /// `level * output_views_stride + channel`. uint output_views_offset; @@ -56,7 +56,7 @@ struct Config { uint level_configs_offset; } -/// Input ring and wrapping mask. +/// Output ring and wrapping mask. struct RingView { /// Offset from input device address. Coerce to `float*`. uint offset; @@ -71,22 +71,27 @@ struct LevelConfig { uint weights_offset; /// Half-width of the filter support, in input samples. Also the index of - /// the center weight, and the fold count minus one. 12 / 24 / 48. + /// the center weight, and the fold count minus one. 10 / 20 / 40 / 80. uint radius; - /// Input samples between consecutive outputs: 2 / 4 / 8. A stride in the - /// sample domain. + /// Input samples between consecutive outputs: 2 / 4 / 8 / 16. A stride in + /// the sample domain. uint decimation_log2; - /// Lanes cooperating on one output: 1 / 2 / 4. A fanout in the lane - /// domain. Equal to decimation/2 today, but they are different kinds of - /// quantity and the shader keeps them apart. + /// Lanes cooperating on one output: 2 / 4 / 8 / 16. A fanout in the lane + /// domain, sized by the host to cover `radius` taps at PAIRS_PER_LANE each. uint lanes_per_output_log2; } struct PushConstants { + uint64_t input_base; uint64_t static_base; + /// Bytes between consecutive channels in the input ring. + uint input_stride; + /// Index wrapping mask for the input ring, in samples. + uint input_mask; + /// Physical index, already reduced against the input view's mask, of the /// window center for this dispatch's first output at each level. uint first_window_center[LEVELS]; @@ -103,28 +108,26 @@ struct PushConstants { [[vk::push_constant]] ConstantBuffer pc; -// dispatch = (ceil(output_count[0] / 256), LEVELS, channels) +// dispatch = (groups_x, LEVELS, channels) where group_x is set for the +// hungriest level. [WaveSize(LANES)] -[numthreads(LANES, WARPS, 1)] -void main(uint3 group_id : SV_GroupID, uint3 thread_id : SV_GroupThreadID) { +[numthreads(LANES, 1, 1)] +void main(uint3 group_id : SV_GroupID, uint lane : SV_GroupThreadID) { let workgroup = group_id.x; let level = group_id.y; let channel = group_id.z; - let warp = thread_id.y; - let lane = thread_id.x; - Config config = *(Ptr)pc.static_base; LevelConfig level_config = ((Ptr)(pc.static_base + config.level_configs_offset))[level]; - RingView input_view = - ((Ptr)(pc.static_base + config.input_views_offset))[channel]; + Ptr input_ring = + (Ptr)(pc.input_base + (uint64_t)(channel * pc.input_stride)); + RingView output_view = ((Ptr)(pc.static_base + config.output_views_offset)) [level * config.output_views_stride + channel]; - Ptr input_ring = (Ptr)(config.input_base + (uint64_t)input_view.offset); Ptr output_ring = (Ptr)(config.output_base + (uint64_t)output_view.offset); Ptr weights = (Ptr)(pc.static_base + level_config.weights_offset); @@ -137,44 +140,48 @@ void main(uint3 group_id : SV_GroupID, uint3 thread_id : SV_GroupThreadID) { let tap_slice = lane & (lanes_per_output - 1); let output_slot = lane >> fanout_log2; - // Concatenate (workgroup, warp, output_slot) into this dispatch's output run. - let outputs_per_warp = LANES >> fanout_log2; - let outputs_per_workgroup = WARPS * outputs_per_warp; - let output_index = workgroup * outputs_per_workgroup - + warp * outputs_per_warp - + output_slot; + // Concatenate (workgroup, output_slot) into this dispatch's output run. + // The host sizes the grid to the hungriest level, so shallower levels run + // ragged and retire here. + let output_index = workgroup * (LANES >> fanout_log2) + output_slot; + + // Uniform across a cooperating group: output_index ignores the low + // fanout_log2 bits of `lane`, which is exactly what the reduction's + // partners vary. So the whole group retires together and the shuffles + // below never reach an exited lane. + if (output_index >= pc.output_count[level]) return; // Physical index of the sample at the center of this output's window. // Underflows below on `- radius + tap` are intentional: two's-complement // wrap composed with a power-of-two mask is the ring wrap. let window_center = pc.first_window_center[level] + output_index * decimation; - // Twelve unconditional folded pairs. Each lane walks its own arithmetic - // progression of tap indexes, striding by the fanout so the outermost (and - // smallest) weights land in every accumulator first. + // Five unconditional folded pairs. Each lane walks its own arithmetic + // progression of tap indexes, striding by the fanout so the outermost + // (and smallest) weights land in every accumulator first. float sum = 0.0f; [ForceUnroll] - for (uint fold = 0; fold < FOLDS_PER_LANE - 1; ++fold) { - let tap = tap_slice + fold * lanes_per_output; - let lower = (window_center - radius + tap) & input_view.mask; - let upper = (window_center + radius - tap) & input_view.mask; - sum = mad(weights[tap], input_ring[lower] + input_ring[upper], sum); - } - - // The unpaired center tap. `radius` is 12 / 24 / 48, all divisible by the - // fanout, so it always falls to slice zero -- the same lane the reduction - // below converges on, and the same lane that stores. + for (uint fold = 0; fold < PAIRS_PER_LANE; ++fold) { + let tap = tap_slice + fold * lanes_per_output; + let lower = (window_center - radius + tap) & pc.input_mask; + let upper = (window_center + radius - tap) & pc.input_mask; + sum = mad(weights[tap], input_ring[lower] + input_ring[upper], sum); + } + + // The unpaired center tap. `radius` is divisible by the fanout at every + // level, so it always falls to slice zero -- the same lane the reduction + // converges on, and the same lane that stores. if (tap_slice == 0) { - sum = mad(weights[radius], input_ring[window_center & input_view.mask], sum); + sum = mad(weights[radius], input_ring[window_center & pc.input_mask], sum); } - // Collapse the cooperating lanes onto slice zero. Zero-trip at 2x. - let lane_index = WaveGetLaneIndex(); + // Collapse the cooperating lanes onto slice zero. One warp per workgroup, + // so `lane` is the wave lane index. Intra-wave: fanout is at most 16. for (uint step = 1; step < lanes_per_output; step <<= 1) { - sum += WaveShuffle(sum, lane_index ^ step); + sum += WaveShuffle(sum, lane ^ step); } - if (tap_slice == 0 && output_index < pc.output_count[level]) { + if (tap_slice == 0) { let destination = (pc.first_output_slot[level] + output_index) & output_view.mask; output_ring[destination] = sum; } diff --git a/mutate-visualizer/shaders/audio/spectrum.slang b/mutate-visualizer/shaders/audio/spectrum.slang new file mode 100644 index 00000000..c39e719b --- /dev/null +++ b/mutate-visualizer/shaders/audio/spectrum.slang @@ -0,0 +1,7 @@ +// Copyright 2026 The MuTate Contributors +// SPDX-License-Identifier: MIT OR Apache-2.0 + +[numthreads(1, 1, 1)] +void main(uint3 tid : SV_DispatchThreadID) { + +} diff --git a/mutate-visualizer/src/audio/cwt/mod.rs b/mutate-visualizer/src/audio/cwt/mod.rs new file mode 100644 index 00000000..809397ae --- /dev/null +++ b/mutate-visualizer/src/audio/cwt/mod.rs @@ -0,0 +1,296 @@ +// Copyright 2026 The MuTate Contributors +// SPDX-License-Identifier: MIT OR Apache-2.0 + +//! # Continuous Wavelet Transform +//! +//! > **Colonel Harland Sandurz:** Sir, are we being too literal? +//! > +//! > **Dark Helmet:** No, you fool. We're following orders. We were told +//! > to comb the desert, so we're combing it. +//! +//! The world is too full of blocky FFTs, DFTs, STFTs, Constant-Q Transforms, and other ideas based +//! on using windows to make little phasors shaped like wavelets. The wavelet is by comparison +//! pre-multiplied. This cuts out the awful serial dependency of spinning that little phasor for +//! every single bin. We can of course parallelize the phasor, but why keep generating the same +//! numbers at all? +//! +//! Meet the wavelet transform. It's cheap. We basically just multiply the input by a comb with a +//! lot of teeth. Because it's so cheap and embarrassingly parallel, we can afford a whole lot of +//! teeth. Using downsampled inputs further helps level and reduce work. +//! +//! ## Problem Symmetry & Similarity +//! +//! Unlike the downsampling, not everything fits in L1. The COLA creates potential for really bad +//! read amplification if we don't efficiently combine and re-use loads. +//! +//! - All bins have a computation cost proportionate to their sample rate alone. This allows us to +//! balance work groups over the sample rate alone! +//! - Weights or their conjugates have symmetry, enabling some storage and register savings. +//! - Weights are re-used on each hop of each wavelet. The phase of the output requires correction, +//! but this amortizes well over the window cost. +//! - To use weights contiguously, the number of unique bins in flight and the cache line for each +//! weight read is shared by many lanes. Faster waves complete more windows and their workgroups +//! move on to the next voice. +//! - The same audio is read heavily by each workgroup, so it is stored in LDS. +//! - Most bin weights fit within a similar range of lengths thanks to the (coincidental but +//! natural) octave structure of the downsampling. +//! +//! ## Outputs +//! +//! Most importantly, outputs are complex. During integration, the complex values can be +//! interpreted along with `BinConfig` to perform reassignment and synchrosqueezing. +//! +//! Each bin has a delay, hop size, center frequency, sample rate, and gain normalization factor. +//! There is a table of values to assist downstream calculations. +//! +//! **We would do one-ring-per-voice, but voices hop at different rates.**. The plan **for now** is +//! to start using some tiling in the output. In high-frequency output bins, their rings are more +//! contiguous in time. For low-pitch bins that don't retire windows frequently we begin to +//! interleave bins so that loads in time are somewhat contiguous but overlap with bins in pitch, +//! reflecting the likely read pattern and compacting more voices per row in the output buffer, +//! squaring the triangle. +//! +//! ## Implementation Tradeoffs +//! +//! - Voices use downsampled input where available. Small group delay. Massive COLA cost +//! improvement. Some control logic complexity. +//! - Constant Q. We gain minimum voice precision we must have. The cost is moving back to the +//! world of different lengths of windows and different sized hops, reading from different sample +//! rates. Outputs per input quantum vary per bin. +//! +//! ### The Slang +//! +//! Unlike past implementations, this solution approach does not have any partial accumulation state +//! between dispatches. Hops fully retire or are not started at all. This greatly aids uniformity. +//! +//! The naive solutions are instructive. If we did one-voice-per-lane with no hop pipelining, there +//! are often not enough hops in some voices, so lanes would be idle. Weight re-use is good, but +//! each lane will be loading completely unique audio from an unrelated hop, so we starve on load +//! bandwidth or LDS bank contention. +//! +//! We must re-use loads. We can either re-use weight loads by loading more audio or re-use audio +//! loads by loading more weights. Weights use more bytes and are uniform across audio, so we +//! re-use weight loads across more audio by pipelining hops, loading different pieces of audio for +//! which we can re-use weights and paying some registers to store the accumulating hops. +//! +//! To give loads greater memory locality and reduce the LDS pressure, we group `L` lanes by voice +//! and pay a small reduction cost at the close of each hope, which is continuously reduced in the +//! hop pipeline rather than shuffled only at the end. The weight re-use and hop pipelining +//! together keep load latency hidden while greatly reducing the number of loads compared to the +//! naive solution. +//! +//! Now let's formalize a bit to expose the important relations: +//! +//! - `L` lanes per voice. +//! - `P` pipeline depth, in-flight hops for `L` lanes. +//! +//! The rest of the geometry will fall out by deduction. +//! +//! - `K` weights for a given filter. +//! - `h` hop length is about `K/8` for ~8x COLA. +//! - `K/2` is the number of pairs per fold. +//! - `T` tap-pairs per lane = `K / 2L`. +//! - `G` groups per warp ~= `32 / L` +//! - `U` weight block unroll size. +//! +//! The chosen sweet spots are T = ~16, P = 4, L = 2-32 (longest wavelets!), and U = 4. Let's see +//! how that goes. +//! +//! We aim for two workgroups per SM/CU, but that will require knowledge of the device that we don't +//! have convenient yet. It's okay to launch more, and they will use atomics to carve up the +//! voices-hop area. +//! +//! - Workgroups target a single sampling rate at a time to make use of LDS. +//! - Workgroups overlap over bins to enable the scheduler to level hop noise. +//! +//! Some secondary ideas that may wind up implemented or not: +//! +//! - Lanes spiral inward on weights (using symmetry) to accumulate from smallest to largest. +//! - Weights may be stored in a compacted form that trades ALU for load bandwidth / geometry. +//! +//! ## Memory Layout +//! +//! ⚠️ The structures are defined as if intended for mutable and immutable sub-allocations, but in +//! the interest of time, one big mutable allocation is used instead. +//! +//! ## The Wavelet +//! +//! We're going with a Morse family wavelet to start with. See [`wavelet`] module. + +// NEXT We're not using any slang reflection. This is the motivating problem for which we would +// even finish implementing the field checks 🤡. Look at all of these buffer device addresses that +// have some coercion target! This will require some newtype wrapping. Probably the biggest time +// saver would be checking field orders. 99 times out of 10, if any type or alignment is wrong, +// it's because fields are missing, extra, or out of order. That doesn't depend on fine-grained +// size and alignment accounting, so it's probably worth it to begin the JSON imports of reflection +// data and begin checks. +// NEXT Wavelet truncation should cooperate with bin length. Padding helps avoid divergence. If +// we're going to pad, keep some extra accuracy! +// NEXT Some taps are possibly near identical, not just the same length, but actually identical, +// thanks to the octave structure of downsampling. +// XXX Fold is anti-Hermitian for reassignment weights, so we have to unpack the conjugates. + +mod warps; // tests used to calibrate workgroup geometry + +use std::mem::MaybeUninit; + +use ash::vk; +use num_complex::Complex32 as Complex; +use num_traits::One; + +use mutate_lib::{self as utate, prelude::*}; +use utate::dsp::{self, bank, wavelet}; + +use super::downsample::{DownsampleOutput, FILTERS}; + +use super::downsample; +use super::plan; + +const BINS: u32 = 3840; +const WARP_SIZE: u32 = 32; +const MAX_FREQ: f64 = 16_000.0; +const SAMPLE_RATE: f32 = 48_000.0; + +/// Overlap factor for COLA. Hop is `length / COLA`. +const COLA: f64 = 8.0; + +#[derive(Debug, Clone)] +pub struct Dispatch { + // NOTE Using a GPU driven style. Header structure is a `CwtOutput` from which the bin table, + // and batch output can be interpreted downstream. Address just enables host to dispatch. + pub output: DeviceAddress, +} + +// XXX does not exist +#[derive(Debug)] +pub struct Output {} + +struct Config { + // TODO fields +} + +struct ChannelConfig { + // TODO input rings + // TODO output rings +} + +// TODO skeleton for the shader +#[compute_pipeline( + compute = stage!("audio/cwt", Compute, c"main"), + push = push!(CwtPushConstants { + /// Coerces to `DownsampleOutput`. + input_base: DeviceAddress, + /// Coerces to `DftConfig` in slang. Static data offsets use this base. + static_base: DeviceAddress, + /// Coerces to `ChannelState*` in slang. All dynamic offsets are relative to this base. + output_base: DeviceAddress, + + // TODO figure out the actual necessary shape of control fields + }), +)] +pub struct Pipeline; + +/// Continuous Wave Transform +pub struct Cwt { + allocation: MappedAllocation, + pipeline: ComputePipeline, +} + +impl Cwt { + pub fn new(device: &Device, input: DownsampleOutput) -> Result { + // Obtain a set of log spaced bin centers across the audible / prettily drawing range. + let bins = bank::bins(dsp::MIN_FREQ_CHEAP_DRIVERS, 15_000.00, BINS as usize); + + // Every bin has a load that depends only on the sample rate. First, count the bins at each + // sample rate to decide the workgroup density across bin ranges. + let cutoffs = FILTERS + .iter() + .map(|f| f.cutoff(SAMPLE_RATE)) + .collect::>(); + + // Every bin has unique weights, tuned for their exact omega. Some octave structure reuse + // opportunities are left alone for now. We create a flexible allocation for the weights + // since we cannot predict the truncation and alignment without generating the wavelets, + // meaning we're not sure how much device memory we need until we have all the weights in + // memory. + + // Laying out the memory is essentially just walking the sizes and offsets of everything we + // want to put in it, remembering those values to later populate the memory, and allocating + // the total sizes. + + // Walk the static section to find offsets and size. + let mut c = plan::Cursor::default(); + let config_offset = c.push::(1); + + // XXX investigate half taps via warp tool!! + // 24 bytes (six floats) per tap. At 1,303,106 taps, that's 31,274,544 bytes worth of taps + // table and the reason we try to keep each workgroup on a single set of taps. + + let static_bytes = c.align_to(256); + + // Walk the dynamic section to find offsets and size. + let mut c = plan::Cursor::default(); + + let dynamic_bytes = c.len(); + + // allocate + let mut allocation = utate::vulkan::resource::buffer::MappedAllocation::::new( + device, + // XXX wrong size + (static_bytes + dynamic_bytes + 128) as usize, + )?; + + // write control data + + // set up state shadows + + // ROLL Flush likely redundant. This will usually be fully coherent BAR/ReBAR window, but + // that abstraction isn't ready yet. + allocation.flush(device); + + let base = allocation.device_address(device)?; + + Ok(Self { + allocation, + pipeline: ComputePipeline::::new(device)?, + }) + } + + /// For each processing quantum, dispatch once. Barrier the hot region of the input and output + /// buffers. + // DEBT we could not provide a command buffer with a type-erased submission model. This is an + // oversight in the cb module. Fix might involve some indirection on the SubmissionModel. Not + // really important, so just fully specified the submission model instead. + pub fn dispatch( + &mut self, + device: &ash::Device, + cb: &RecordingBuffer, + downsample: &downsample::DownsampleOutput, + ) -> Result { + // calculate indexes + + // push constants + + // dispatch + + // update state shadows + + // publish host data + + Ok(Dispatch { + output: DeviceAddress::NULL, + }) + } + + pub fn destroy(self, device: &Device) { + device.deletion_queue.push(self.allocation.buffer); + device.deletion_queue.push(self.allocation.memory); + self.pipeline.destroy(device); + } + + /// Provides downstreams with an idea where to get output before it even starts flowing. Hope + /// your initializations aren't garbage. ⚝ + pub fn view(&self) -> Output { + Output {} + } +} diff --git a/mutate-visualizer/src/audio/cwt/warps.rs b/mutate-visualizer/src/audio/cwt/warps.rs new file mode 100644 index 00000000..a7c8c56e --- /dev/null +++ b/mutate-visualizer/src/audio/cwt/warps.rs @@ -0,0 +1,173 @@ +// Copyright 2026 The MuTate Contributors +// SPDX-License-Identifier: MIT OR Apache-2.0 + +//! # Warp & Workgroup Planning Analysis +//! +//! A record of how recent GPU workload leveling was planned. + +// NOTE A lot of modules need to start migrating back into lib. Until then, the imports were +// inconvenient. +// DEBT slang libraries so we can put this and associated code into lib and import them into the +// visualizer. + +use super::{BINS, COLA, MAX_FREQ, SAMPLE_RATE}; + +#[cfg(test)] +mod test { + + use super::*; + + use mutate_lib::dsp::{self, bank, wavelet::WaveletSpec, MIN_FREQ_CHEAP_DRIVERS}; + + use crate::audio::downsample::FILTERS; + + const LOAD_QUANTUM: usize = 8; + + fn spec() -> WaveletSpec { + WaveletSpec::default().max_load_quantum(16) + } + + fn bins() -> Vec { + bank::bins(dsp::MIN_FREQ_CHEAP_DRIVERS, MAX_FREQ, BINS as usize) + } + + // NOTE Whole module assumes that filters are in order of decreasing cutoffs, but alternative + // filter designs with higher frequency cutoffs for a given decimation have been proposed. If + // the sorting of filters and cutoffs changes, some assumptions will need revisiting. + fn cutoffs() -> Vec { + FILTERS + .iter() + .map(|f| f.cutoff(SAMPLE_RATE)) + .collect::>() + } + + #[test] + fn downsampling_rate_bins_histogram() { + // For this test, we just want to know the sample rates that our bins wind up using. It's a + // decent check for how often we need each input rate loaded. Workgroups cannot work on a + // bin without the audio in the LDS, so before anything else happens, we have to balance the + // workgroups to the downsampling rates. + + let bins = bins(); + let cutoffs = cutoffs(); + + // Bins above all cutoffs use the full sampling rate. + let mut counts = vec![0usize; cutoffs.len() + 1]; + for b in bins.iter() { + counts[cutoffs.partition_point(|&c| c > b.center as f32)] += 1; + } + + for (i, n) in counts.iter().enumerate() { + let cutoff = if i == 0 { + 0.5 * SAMPLE_RATE + } else { + cutoffs[i - 1] + }; + println!("cutoff {cutoff}: {n} bins"); + } + } + + #[test] + fn downsampling_rate_taps_histogram() { + // This test enables us to see the memory sizes of taps and estimate both total taps we need + // in L2 / LDS and the taps memory demand and how sensitive we are to further downsampling. + // We can also estimate the taps sizes for individual workgroup LDS and assign warps more + // effectively. + + let bins = bins(); + let cutoffs = cutoffs(); + + let p = spec().plan(); + + // Bins above all cutoffs use the full sampling rate. + let mut buckets = vec![0usize; usize::BITS as usize]; + let mut total = 0usize; + + for b in bins.iter() { + let level = cutoffs.partition_point(|&c| c > b.center as f32); + let decimation = if level == 0 { + 1 + } else { + FILTERS[level - 1].decimation + }; + let rate = SAMPLE_RATE / decimation as f32; + let taps = p.bin(b.center, rate as f64, LOAD_QUANTUM).unfolded_taps() as usize; + + buckets[usize::BITS as usize - 1 - taps.leading_zeros() as usize] += 1; + total += taps; + } + + for (lg, n) in buckets.iter().enumerate() { + if *n != 0 { + println!("{:>7}..{:<7} {n} bins", 1usize << lg, (2usize << lg) - 1); + } + } + println!("total taps {total}"); + } + + #[test] + fn downsampling_rate_macs_histogram() { + // This test attempts to expose the MAC rates and show us the need for MAC leveling across + // the sample rates. We need approximately proportionate amounts of lanes that can reach + // MAC dense regions of the workload. The memory requirements of those workgroups are known + // from the taps histogram while the assignment density is more reflected in the bin + // histogram. We will need to naturally (without too much atomic contention and flow + // control) balance all of these concerns when deciding our workgroup plan. + + let bins = bins(); + let cutoffs = cutoffs(); + + let p = spec().plan(); + + // Bins above all cutoffs use the full sampling rate. + let mut buckets = vec![0usize; usize::BITS as usize]; + let mut levels = vec![(0usize, 0.0f64, 0usize); cutoffs.len() + 1]; + let mut mac_s = 0.0f64; + + for b in bins.iter() { + let level = cutoffs.partition_point(|&c| c > b.center as f32); + let decimation = if level == 0 { + 1 + } else { + FILTERS[level - 1].decimation + }; + let rate = SAMPLE_RATE / decimation as f32; + let taps = p.bin(b.center, rate as f64, LOAD_QUANTUM).unfolded_taps() as usize; + + // length cancels: (rate * COLA / taps) outputs/s * taps MAC/output + let bin_mac_s = COLA * rate as f64; + mac_s += bin_mac_s; + + let l = &mut levels[level]; + l.0 += 1; + l.1 += bin_mac_s; + l.2 = l.2.max(taps); + + buckets[usize::BITS as usize - 1 - taps.leading_zeros() as usize] += 1; + } + + println!("=== TAP LENGTHS (ring size / latency, not cost) ==="); + for (lg, n) in buckets.iter().enumerate() { + if *n != 0 { + println!("{:>7}..{:<7} {n} bins", 1usize << lg, (2usize << lg) - 1); + } + } + + println!("\n=== COST (COLA {COLA:.0}x) ==="); + for (i, &(n, c, max_taps)) in levels.iter().enumerate() { + if n == 0 { + continue; + } + let decimation = if i == 0 { 1 } else { FILTERS[i - 1].decimation }; + let rate = SAMPLE_RATE / decimation as f32; + println!( + " /{decimation:<3} rate {rate:>8.0} {n:>4} bins \ + {:>9.2} MMAC/s worst window {:>6} taps = {:>7.1} ms", + c / 1e6, + max_taps, + 1e3 * max_taps as f64 / rate as f64, + ); + } + println!("\n total {:.2} MMAC/s", mac_s / 1e6); + } +} diff --git a/mutate-visualizer/src/audio/downsample/mod.rs b/mutate-visualizer/src/audio/downsample/mod.rs index 1b7bab2a..1d2c9e21 100644 --- a/mutate-visualizer/src/audio/downsample/mod.rs +++ b/mutate-visualizer/src/audio/downsample/mod.rs @@ -10,141 +10,238 @@ //! > - Frederick Allan Moranis //! //! Long filter windows cost a lot. Downsampling reduces the cost. We FIR low-pass and decimate to -//! save on cost. Savings taper off (fewer bins affected and less absolute input length reduction) -//! while delay goes up for extreme downsampling, so we eat the cost in the lowest octaves. High -//! pitch samples are incidentally attenuated with a safety margin that makes the output signal +//! save on cost. Savings taper off (fewer bins affected and less absolute input rate reduction) +//! while delay goes up for extreme downsampling, so we eat the rate cost in the lowest octaves. +//! High pitches are incidentally attenuated, providing a safety margin that makes the output signal //! cleaner than it was if the same bins are filtering the full-rate input. //! -//! - 8x downsampling for use below 1/32 Nyquist input -//! - 4x downsampling for use below 1/16 Nyquist input -//! - 2x downsampling for use below 1/8 Nyquist input +//! - 2x downsampling for use below 1/4 Nyquist input +//! - 4x downsampling for use below 1/8 Nyquist input +//! - 8x downsampling for use below 1/16 Nyquist input +//! - 16x downsampling for use below 1/32 Nyquist input down to DC //! -//! Biggest savings for the longest bins basically achieved. +//! Biggest savings for the longest bins basically achieved already, so no 32x downsampling is +//! planned, although the GPU will happily crunch it in dozens of cycles at most. //! -//! This is a fairly naive implementation, using several lanes per frame, just to get going. Feel -//! free to look for other techniques, but the main on-device constraint for FIR downsampling seems -//! to be that serial dependencies across warps are absolutely terrible, so going directly from -//! signal to output is almost always going to win. +//! ## The Slang //! -//! ## The Weights +//! The shader is built around single-stage, direct FIR from full rate to target rate for every +//! downsampling level. While the filters are long, the data sharing is minimal and we use several +//! lanes per frame, more lanes for longer filters to level the load across warps. For an audio +//! tick of 512 samples and two channels, there's about 80k MACs, barely enough to occupy all SMs +//! before the entire filter is already done. The output sample rate goes down as fast as the +//! filter size increases, so this solution remains linear. +//! +//! Feel free to look for other techniques, but the main on-device constraint for FIR downsampling +//! seems to be that serial dependencies across warps are absolutely terrible, so going directly +//! from signal to output without any kind of cascading is almost always going to win. The device +//! has enough lanes that a single audio server tick will struggle to make use of the full width +//! available anyway. //! -//! There is a trick of the down-sample folding used to achieve a really big transition band. We -//! guarantee attenuation of noise from folding rather than no folded noise at all. Input at the -//! new sample rate Nyquist, reach about 0.35 on a peak detector post filter, or about -9dB, leaving -//! a net of about -3dB for folded noise. We don't use the area right at the new Nyquist, so this -//! is fine? In theory, but maybe not practice. We will defer to the opinions of long-time DSP -//! professionals through an open source development process. +//! The whole problem fits in L1, and there are barely enough outputs to issue on every warp as it +//! is, so hiding latency and leveling tails is probably best done with more workgroups rather than +//! LDS or pipelining outputs. //! -//! ⚠️ As a result of this design feature, bins should be very careful to **not let their main lobe -//! get into the transition band.** The transition band will be corrupted. Use a higher sample rate -//! and the transition will be nowhere near where you are analyzing 😼. +//! ## The Weights //! -//! Pre-decimation FIR low-pass that crushes everything above 1/2 input Nyquist, using a wide 1/4 to +//! Pre-decimation FIR low-pass that crushes everything above 3/4 input Nyquist, using a wide 1/4 to //! 3/4 Nyquist as the transition band. Parks McClellan Remez weight generation. With the wide //! transition, we get: //! //! - Low ripple in the pass so signal we want is unchanged. -//! - Post-fold transition noise is at last -6dB dampened, so it will net attenuate post-fold and be +//! - Post-fold transition noise is at least -6dB dampened, so it will net attenuate post-fold and be //! easier to filter from the pass band. //! - Some extra stop band cushion so that bins at the top of the new pass band won't see folded //! transition. //! - Some extra pass band cushion so that bins at the top of the pass can perform reassignment of //! their full main lobe. -//! - About 80dB stop band attenuation so our bins in the pass aren't seeing the folded noise. -//! - Odd weights fitted to make decent use of warps. +//! - About -90dB stop band attenuation so our bins in the pass aren't seeing the folded signals. +//! - Odd numbers of taps, fitted to neatly level the load across warps. +//! +//! There is a **trick** of the down-sample folding used to achieve a really big transition band. +//! We guarantee *attenuation* of folded regions rather than setting the stop band to the new +//! Nyquist. The ripple continues beyond the new Nyquist, all the way up to the folding mirror of +//! the pass band edge. +//! +//! We can obtain sufficient transition attenuation with a lower number of taps. This would buy us +//! some delay reduction at the cost of more ripple, likely in the pass band, or less noise floor +//! margin. //! -//! We can obtain sufficient transition attenuation with a lower number of taps. This trades delay, -//! which would become significant at higher downsampling rates. +//! ### Filter Sharp Edges +//! +//! Output at the new sample rate Nyquist is only guaranteed to be *attenuated* from the source +//! signal or noise, but not attenuated as deeply as the true stop band, and would still be evident +//! within the usable *dynamic ranges* of the pass band (not the pitch ranges). We don't use the +//! area right at the new Nyquist, so this is fine? In theory, but maybe not practice. We will +//! defer to the opinions of long-time DSP professionals through an open source development process. +//! +//! ⚠️ As a result of the transition admitting reflected signal, especially near the new Nyquist, +//! bins should be very careful to **not let their main lobe get into the transition band.** Beyond +//! the transition band guard, folded signals and noise begin ramping all the way to the new +//! Nyquist. Use a higher sample rate and the transition will be nowhere near where you are +//! analyzing 😼. +//! +//! ⚠️ Filter bank design should be aware that the transition contains extreme grooves and undefined +//! attenuation that may scallop main lobes or obliterate side lobes. This may lead to grooves in +//! the overall response if not calibrated. Again, use a higher sample rate if there's a problem! //! //! ## Delay //! -//! A uniform group delay per octave was chosen just to be tidy. This kind of nicety on the output -//! may have usage for others. The filters use 25/49/97 taps for a delay of 6 between each "stage" -//! (they are direct, not cascaded). - -// DEBT I keep writing const generics for the channels. At some point let's reverse this to runtime -// configuration. +//! A uniform group delay per octave was chosen just to be tidy. 21/41/81/161 taps give 5 +//! **output** samples of relative delay at each successive level. + +// MAYBE Publish a semaphore value to readback for the host to be able to decide how much input +// dispatched upon is now ready for producer reclaim. +// NEXT Write the LEVELS output ring offset data to a header so that the host side of sharing +// downstream is dynamic state only. We will need to start doing slang libraries, but we absolutely +// should! +// NEXT Upstream bursts and downstream read floor contracts require one solution. We should +// consider the oldest half of the output ring always ready for reclaim. We should clamp the read +// onto the *newest* data on the input ring, adjusting our indexes and the consumed counts so that +// subsequent reads will properly jump ahead and skip our old data. The audio graph dispatch cycle +// guarantees that this *effective double buffering* is good enough. A follow-on plan for the audio +// import ring is to swallow such bursts using a triple-buffer with rotation so that, in the worst +// case, we see 1/3 of the ring size of fresh data when we come back around. Downsampler will then +// fill half of its rings with fresh data and the audio graph will consume only that on the tick. +// Either the import or the downsampler should tell downtreams to flush the discontinuity by setting +// reclaim indexes. Output rings will require a second triple-buffering fixup to account for +// consumers in flight. Ring buffers man! mod weights; use ash::vk; -use mutate_lib::{self as utate, audio::import::RingLayout, prelude::*}; +use mutate_lib::{self as utate, audio::import::DeviceAudioView, prelude::*}; use super::plan; +/// Must match `LANES` in audio/downsample.slang. +const LANES: u32 = 32; + +/// Outputs a workgroup emits at `level`: 16 / 8 / 4 / 2. +const fn outputs_per_workgroup(level: usize) -> u32 { + LANES / lanes_per_output(level) +} + +const LEVELS: usize = 4; +pub const FILTERS: [weights::Lowpass; LEVELS] = [ + weights::DOWN_TWO, + weights::DOWN_FOUR, + weights::DOWN_EIGHT, + weights::DOWN_SIXTEEN, +]; + +/// Input samples per output sample. A stride in the sample domain, and a +/// property of the filter, not the level's position in the table. +const fn decimation_log2(level: usize) -> u32 { + FILTERS[level].decimation.trailing_zeros() +} + +/// Lanes cooperating on one output: 2 / 4 / 8 / 16. A fanout in the lane +/// domain -- exactly the lanes needed to cover `radius` taps at +/// `PAIRS_PER_LANE` each. Must stay <= LANES: above that the reduction +/// crosses the wave and `WaveShuffle` no longer reaches. +const fn lanes_per_output(level: usize) -> u32 { + FILTERS[level].radius() / PAIRS_PER_LANE +} + +const fn lanes_per_output_log2(level: usize) -> u32 { + lanes_per_output(level).trailing_zeros() +} + +/// Output rings are implicitly longer in time, enough to accommodate the longest spans any +/// downstream filter wants to read. Low pitch filters will sometimes want to reach back in time, +/// and this storage is cheap, so we just keep it available. +// NOTE scaled back to input rate: 8192, 8192, 16384, 32768, almost 1s of 48kHz input. +const LEVEL_SAMPLES: [u32; LEVELS] = [4096, 2048, 2048, 2048]; + +/// How far back in *input* samples each level's ring reaches. No longer uniform across levels +/// and not derivable from any other level -- downstream must read this rather than shift. +const fn level_span(level: usize) -> u64 { + LEVEL_SAMPLES[level] as u64 * FILTERS[level].decimation as u64 +} + +/// Must match `PAIRS_PER_LANE` in audio/downsample.slang. +const PAIRS_PER_LANE: u32 = 5; + +const _: () = { + let mut level = 0; + while level < LEVELS { + // The fold divides exactly: every cooperating lane gets PAIRS_PER_LANE + // pairs and the center lands on slice zero. + assert!(FILTERS[level].radius() % PAIRS_PER_LANE == 0); + // Fanout must be PoT for the mask/shift split and the butterfly. + assert!(lanes_per_output(level).is_power_of_two()); + assert!(lanes_per_output(level) <= LANES); + // Decimation must be PoT for the shift in write_head / first_output_slot. + assert!(FILTERS[level].decimation.is_power_of_two()); + assert!(LEVEL_SAMPLES[level].is_power_of_two()); + level += 1; + } +}; + +/// One level of downsampling. A set of `Rings` and metadata about the decimation and cutoff +/// frequency. #[derive(Clone, Copy, Debug)] -pub struct LevelOutput { - /// Absolute base of each channel's ring. - pub channels: [DeviceAddress; CHANNELS], - /// Ring capacity in samples. PoT; mask is `sample_count - 1`. - pub sample_count: u32, - /// Monotonic count of samples written at *this level's* rate. - /// Physical slot is `write_head & (sample_count - 1)`. +pub struct LevelOutput { + /// Offset from the output base address. + pub offset: u32, + /// Output samples ever written at this level. pub write_head: u64, - /// `1 << (level + 1)`. Input samples per output sample at this level. + /// Number of channels + pub channel_count: u32, + /// Number of samples in each channel + pub sample_count: u32, + /// Input samples per output sample. pub decimation: u32, + /// Highest frequency (Hz) a bin center may sit at. + pub cutoff: f32, + /// Group delay in input samples. + pub delay: u32, + /// Oldest input-domain sample still resident in this level's ring, relative to `write_head` + /// scaled to input rate. Reach-back budget for downstream filters. + pub span_input_samples: u64, } -impl LevelOutput { +impl LevelOutput { pub fn mask(&self) -> u32 { self.sample_count - 1 } - pub fn write_slot(&self) -> u32 { - self.write_head as u32 & self.mask() - } } -/// Geometry, location, and tracking for downstream consumers of all levels. +/// Location, #[derive(Clone, Copy, Debug)] -pub struct DownsampleOutput { - base: DeviceAddress, - ring_offsets: [[u32; CHANNELS]; LEVELS], - /// Logical input index of the next window center. The whole clock lives here: - /// level `L`'s write head is `next_center >> (L + 1)`. - pub next_center: u64, - /// Oldest input sample still readable by this module. Import honors this. - pub retain_floor: u64, - /// Signaled once this dispatch's writes are visible. - pub data_ready: WaitValue, +pub struct DownsampleOutput { + /// All channels in the payload are based 🥷🏿. + pub base_address: DeviceAddress, + /// Each output level has metadata and channels. + pub levels: [LevelOutput; LEVELS], } -impl DownsampleOutput { - pub fn level(&self, level: usize) -> LevelOutput { - LevelOutput { - channels: std::array::from_fn(|ch| { - (self.base.raw() + self.ring_offsets[level][ch] as u64).into() - }), - sample_count: LEVEL_SAMPLES[level], - write_head: self.next_center >> (level + 1), - decimation: 1 << (level + 1), - } +impl DownsampleOutput { + /// Deepest level whose read band covers `center_hz`. `None` means the frequency belongs to + /// the full-rate stream. Assumes the last level is terminal, so nothing falls out the bottom. + pub fn level_for(&self, center_hz: f32) -> Option { + (0..LEVELS) + .rev() + .find(|&l| center_hz <= self.levels[l].cutoff) } } -pub struct DownsampleDispatch { - pub output: DownsampleOutput, - pub ready: SignalIntent, +pub struct DownsampleDispatch { + pub output: DownsampleOutput, + // NEXT make the upstream DeviceAudioImport accept an absolute head rather than relative + // "consumed". + /// Oldest input sample still needed. Import may reclaim strictly below. + pub retain_floor: u64, + /// Floor delta. pub consumed: u32, } -pub const LEVELS: usize = 3; - -/// Folded weight counts: `radius + 1` for 25/49/97 taps. -const RADIUS: [u32; LEVELS] = [12, 24, 48]; -const _: () = assert!(weights::DOWN_TWO.len() as u32 == RADIUS[0] * 2 + 1); -const _: () = assert!(weights::DOWN_FOUR.len() as u32 == RADIUS[1] * 2 + 1); -const _: () = assert!(weights::DOWN_EIGHT.len() as u32 == RADIUS[2] * 2 + 1); - /// Header of the static base. #[repr(C)] struct Config { - /// Base of the *input* rings. Upstream's allocation, not ours. - input_base: DeviceAddress, /// Base of our dynamic section. Written after allocation; see `new`. output_base: DeviceAddress, - - /// -> `RingView[CHANNELS]`, from `static_base`. - input_views_offset: u32, /// -> `RingView[LEVELS * CHANNELS]`, from `static_base`. output_views_offset: u32, /// Major stride of the output view table. == CHANNELS. @@ -153,9 +250,10 @@ struct Config { level_configs_offset: u32, } +// XXX maybe not actually pub #[repr(C)] #[derive(Clone, Copy)] -struct RingView { +pub struct RingView { /// Offset from the relevant base, in *bytes*. offset: u32, /// Index wrap mask, in *samples*. @@ -174,48 +272,55 @@ struct LevelConfig { #[compute_pipeline( compute = stage!("audio/downsample", Compute, c"main"), push = push!(PushConstants { + /// Base of the *input* rings. Upstream's allocation, not ours. + input_base: DeviceAddress, /// Coerces to `Config` in slang. Static data offsets use this base. static_base: DeviceAddress, + /// Bytes between input rings + input_stride: UInt, + /// Index wrapping mask for input ring, in samples + input_mask: UInt, + /// Physical index of the center sample where the first downsample filter will be applied. - first_window_center: [UInt; 3], + first_window_center: [UInt; 4], /// Physical index of the first output slot - first_output_slot: [UInt; 3], + first_output_slot: [UInt; 4], /// How many outputs write, - output_count: [UInt; 3], + output_count: [UInt; 4], }), )] pub struct Pipeline; -/// LCM of the decimation factors. The scheduling quantum, in input samples. -const INPUT_QUANTUM: u64 = 1 << LEVELS; // 8 -/// Level-0 outputs per quantum. `count[0]` is always a multiple of this. -const OUTPUT_QUANTUM: u64 = INPUT_QUANTUM / 2; // 4 -/// Deepest lookahead demanded by any level. Level 2 binds. -const MAX_RADIUS: u64 = RADIUS[LEVELS - 1] as u64; // 48 - -// The levels saturate their output rings together: 4096 >> L == LEVEL_SAMPLES[L]. - -pub struct Downsample { +pub struct Downsample { allocation: MappedAllocation, /// Bases are handed to the device every dispatch via push constants static_base: DeviceAddress, output_base: DeviceAddress, - output_ring_offsets: [[u32; CHANNELS]; LEVELS], - pipeline: ComputePipeline, + output_channel_count: u32, + output_level_count: u32, + /// Byte offset from `output_base` to each level's channel 0. + output_level_offsets: [u32; LEVELS], + + pipeline: ComputePipeline, timeline: TimelineSemaphore, - /// For now, we might get away with a very specific rate of advance. Given that downsample - /// frames never tick downstream except on certain inputs, this might actually work. - next_center: u64, -} + /// Next window center per level, in input samples. Levels advance independently; each is a + /// multiple of its own decimation, so `next_centers[l] >> decimation_log2(l)` is that level's + /// output write head. + next_centers: [u64; LEVELS], + + /// Upstream sample rate. + sample_rate: u32, -const LEVEL_SAMPLES: [u32; LEVELS] = [4096, 2048, 1024]; + /// Tracking floor delta to report consumed. + prev_retain_floor: u64, +} -impl Downsample { - pub fn new(device: &Device, ring_layout: RingLayout) -> Result { +impl Downsample { + pub fn new(device: &Device, channels: u32, sample_rate: u32) -> Result { // NOTE The big idea is no different for any of these pipelines. We plan the layout, grab // the allocation, initialize it, and set up our local state shadows we'll need for later // dispatch. @@ -223,23 +328,20 @@ impl Downsample { // plan static let mut c = plan::Cursor::default(); let config_offset = c.push::(1); - let input_views_offset = c.push::(CHANNELS as u32); - let output_views_offset = c.push::((LEVELS * CHANNELS) as u32); + let output_views_offset = c.push::(LEVELS as u32 * channels); let level_configs_offset = c.push::(LEVELS as u32); let mut weights_offsets = [0u32; LEVELS]; for level in 0..LEVELS { - weights_offsets[level] = c.push::(RADIUS[level] + 1); + weights_offsets[level] = c.push::(FILTERS[level].radius() + 1); } let static_bytes = c.align_to(256); // plan outputs let mut c = plan::Cursor::default(); - let mut output_ring_offsets = [[0u32; CHANNELS]; LEVELS]; + let mut output_level_offsets = [0u32; LEVELS]; for level in 0..LEVELS { - for ch in 0..CHANNELS { - output_ring_offsets[level][ch] = c.push::(LEVEL_SAMPLES[level]); - } + output_level_offsets[level] = c.push::(LEVEL_SAMPLES[level] * channels); } let dynamic_bytes = c.len(); @@ -248,73 +350,39 @@ impl Downsample { (static_bytes + dynamic_bytes) as usize, )?; - // Address first: an immutable borrow that ends here, before the split below takes the - // allocation mutably for the rest of the function. let base = allocation.device_address(device)?; let static_base: DeviceAddress = base.into(); + // FIXME Output belongs in a separate allocation. We can use device-only memory after the + // transfer-initialization dance is set supported. let output_base: DeviceAddress = (base + static_bytes as u64).into(); - // XXX isn't the "dynamic" address the output address? Where else would we enable writes if - // we later do a static-dynamic allocation split? - let (stat, _dynam) = allocation - .as_mut_slice() - .split_at_mut(static_bytes as usize); + let stat = allocation.as_mut_slice(); plan::put( stat, config_offset, Config { - input_base: ring_layout.base_address.into(), output_base, - input_views_offset, output_views_offset, - output_views_stride: CHANNELS as u32, + output_views_stride: channels, level_configs_offset, }, ); - // Folded, outward-in: index 0 is the outermost tap, index `radius` is the center. - // Symmetry is asserted above, so the leading half is the whole story. - plan::put_slice( - stat, - weights_offsets[0], - &weights::DOWN_TWO[..=RADIUS[0] as usize], - ); - plan::put_slice( - stat, - weights_offsets[1], - &weights::DOWN_FOUR[..=RADIUS[1] as usize], - ); - plan::put_slice( - stat, - weights_offsets[2], - &weights::DOWN_EIGHT[..=RADIUS[2] as usize], - ); - - // TODO - // Host state tracking data... - - // Input views: upstream ring, per channel. - for ch in 0..CHANNELS { - plan::put( - stat, - input_views_offset + ch as u32 * size_of::() as u32, - RingView { - offset: ring_layout.channel_offsets[ch], - mask: ring_layout.sample_count - 1, - }, - ); + // Weights are symmetric, so we store half. + for level in 0..LEVELS { + plan::put_slice(stat, weights_offsets[level], FILTERS[level].folded()); } // Output views: [level][channel], stride == CHANNELS. for level in 0..LEVELS { - for ch in 0..CHANNELS { - let i = (level * CHANNELS + ch) as u32; + for ch in 0..channels { + let i = level as u32 * channels + ch; plan::put( stat, output_views_offset + i * size_of::() as u32, RingView { - offset: output_ring_offsets[level][ch], + offset: output_level_offsets[level] + ch * LEVEL_SAMPLES[level] * 4, mask: LEVEL_SAMPLES[level] - 1, }, ); @@ -327,69 +395,82 @@ impl Downsample { level_configs_offset + level as u32 * size_of::() as u32, LevelConfig { weights_offset: weights_offsets[level], - radius: RADIUS[level], - decimation_log2: level as u32 + 1, - lanes_per_output_log2: level as u32, + radius: FILTERS[level].radius(), + decimation_log2: decimation_log2(level), + lanes_per_output_log2: lanes_per_output_log2(level), }, ); + debug_assert!(lanes_per_output_log2(level) == decimation_log2(level)); } Ok(Self { allocation, static_base, output_base, - output_ring_offsets, - timeline: device.make_timeline_semaphore()?, - // NEXT Just...emit an alias already. + output_level_offsets, + output_channel_count: channels, + output_level_count: LEVELS as u32, pipeline: ComputePipeline::::new(device)?, - next_center: 0, + timeline: device.make_timeline_semaphore()?, + next_centers: std::array::from_fn(|l| FILTERS[l].radius() as u64), + sample_rate, + prev_retain_floor: 0, }) } - // NOTE The dft.rs accepts a layout on new and stores it in the config. This shader pub fn dispatch( &mut self, device: &ash::Device, cb: &RecordingBuffer, - input: &DeviceRingView, - ) -> Result, MutateError> { + input: &DeviceAudioView, + ) -> Result { // Calculate the downsampler advances from the upstream write head. - let count = self.ready_outputs(input.write_head); - let input_mask = input.ring_layout.sample_count - 1; + let counts: [u32; LEVELS] = + std::array::from_fn(|l| self.ready_at(l, input.write_head, input.sample_count as u64)); + + let input_mask = input.sample_count - 1; let constants = PushConstants { + input_base: input.base_address, static_base: self.static_base, - first_window_center: std::array::from_fn(|_| { - ((self.next_center as u32) & input_mask).into() + input_stride: (input.sample_count * 4).into(), + input_mask: input_mask.into(), + + first_window_center: std::array::from_fn(|l| { + ((self.next_centers[l] as u32) & input_mask).into() }), first_output_slot: std::array::from_fn(|l| { - (((self.next_center >> (l + 1)) as u32) & (LEVEL_SAMPLES[l] - 1)).into() + (((self.next_centers[l] >> decimation_log2(l)) as u32) & (LEVEL_SAMPLES[l] - 1)) + .into() }), - output_count: std::array::from_fn(|l| (count >> l).into()), + output_count: std::array::from_fn(|l| counts[l].into()), }; self.pipeline.push(device, **cb, &constants); - let groups_x = count.div_ceil(256); + // NOTE Width covers the hungriest level. Shallower levels over-provision no-op workgroups. + // The upstream callback already early returns on zero-sized audio server ticks. + let groups_x = (0..LEVELS) + .map(|l| counts[l].div_ceil(outputs_per_workgroup(l))) + .max() + .unwrap() + .max(1); + unsafe { device.cmd_bind_pipeline(**cb, vk::PipelineBindPoint::COMPUTE, *self.pipeline); - device.cmd_dispatch(**cb, groups_x, LEVELS as u32, CHANNELS as u32); + device.cmd_dispatch(**cb, groups_x, LEVELS as u32, self.output_channel_count); } - self.next_center += count as u64 * 2; - debug_assert_eq!(self.next_center % INPUT_QUANTUM, 0); + for l in 0..LEVELS { + self.next_centers[l] += counts[l] as u64 * FILTERS[l].decimation as u64; + } - let ready = self.timeline.next_signal(); - let output = DownsampleOutput { - base: self.output_base, - ring_offsets: self.output_ring_offsets, - next_center: self.next_center, // already advanced above - retain_floor: self.retain_floor(), - data_ready: ready.wait_value(), - }; + let retain_floor = self.retain_floor(); + let consumed = (retain_floor - self.prev_retain_floor) as u32; + self.prev_retain_floor = retain_floor; Ok(DownsampleDispatch { - output, - ready, - consumed: count, + output: self.view(), + retain_floor, + consumed, }) } @@ -400,40 +481,59 @@ impl Downsample { self.pipeline.destroy(device); } - /// How many level-0 outputs are ready, given total samples ever written to the - /// input ring. Level `L` gets `count >> L`. + /// Clamps maximum advance to last eligible center. /// - /// An output centered at logical index `c` reads `[c - radius, c + radius]`. - /// Lockstep scheduling means every level waits on `MAX_RADIUS` of lookahead, - /// so the newest center we may close is `written - 1 - MAX_RADIUS`. - fn ready_outputs(&self, written: u64) -> u32 { - let Some(newest_center) = written.checked_sub(1 + MAX_RADIUS) else { - return 0; // ring hasn't filled the first window yet + /// An output centered at `c` reads `[c - radius, c + radius]`, so the newest eligible center + /// is: `written - 1 - radius`, clamped before wrap or exhausting fresh input samples. + fn ready_at(&self, level: usize, written: u64, input_samples: u64) -> u32 { + let radius = FILTERS[level].radius() as u64; + let decimation = FILTERS[level].decimation as u64; + + let Some(newest) = written.checked_sub(1 + radius) else { + return 0; }; - if newest_center < self.next_center { + let newest = newest & !(decimation - 1); + let next = self.next_centers[level]; + if newest < next { return 0; } - // Centers are `next_center, next_center + 2, ..` up to and including newest. - let count = (newest_center - self.next_center) / 2 + 1; - - // Floor to the quantum so every level gets a whole number of outputs, and - // clamp so no level laps its output ring in a single dispatch. - let count = count & !(OUTPUT_QUANTUM - 1); - count.min(LEVEL_SAMPLES[0] as u64 / 2) as u32 + // NOTE During underruns, it would be preferred to consume the newest output and discard the + // older output. More details about double buffering at the mod doc trailer. + let count = (newest - next) / decimation + 1; + let by_output = LEVEL_SAMPLES[level] as u64 / 2; + // Window for the last center reaches `next - radius` .. `next + (n-1)*dec + radius`. + let by_input = (input_samples / 2).saturating_sub(2 * radius) / decimation; + count.min(by_output).min(by_input) as u32 } /// Oldest input sample this module may still read. Import must not reclaim below this. pub fn retain_floor(&self) -> u64 { - self.next_center.saturating_sub(MAX_RADIUS) + (0..LEVELS) + .map(|l| self.next_centers[l].saturating_sub(FILTERS[l].radius() as u64)) + .min() + .unwrap() } - /// Returns on-device geometry for a single level of downsampling outputs. - pub fn level_layout(&self, level: usize) -> RingLayout { - RingLayout { - base_address: self.output_base.raw(), - channel_offsets: self.output_ring_offsets[level], - sample_count: LEVEL_SAMPLES[level], + /// Return the state and layout information independent of dispatching. Useful for initializing + /// downstreams. + pub fn view(&self) -> DownsampleOutput { + let sample_rate = self.sample_rate as f32; + DownsampleOutput { + base_address: self.output_base, + levels: std::array::from_fn(|l| { + let f = &FILTERS[l]; + LevelOutput { + offset: self.output_level_offsets[l], + channel_count: self.output_channel_count, + sample_count: LEVEL_SAMPLES[l], + decimation: f.decimation, + cutoff: f.cutoff(sample_rate), + delay: f.radius(), + write_head: self.next_centers[l] >> decimation_log2(l), + span_input_samples: level_span(l), + } + }), } } } diff --git a/mutate-visualizer/src/audio/downsample/weights.rs b/mutate-visualizer/src/audio/downsample/weights.rs index bbfe10e7..f1e68d3e 100644 --- a/mutate-visualizer/src/audio/downsample/weights.rs +++ b/mutate-visualizer/src/audio/downsample/weights.rs @@ -7,271 +7,541 @@ //! > //! > - Your dad //! -//! Weights generated from the packaged PMR tool. See README to re-generate other lengths. Weights -//! are designed for the shader execution structure. Details on the filter design in downsample.rs. +//! Weights generated from the packaged PMR tool. See README and included command examples to +//! re-generate other lengths. Weights are designed for the shader execution structure. Details on +//! the filter design in downsample.rs. // NEXT Design for main lobe widths! There's a lot of subjective tuning done so far. // NEXT Proc macro! The CLI tool is kind of a dumpster fire just good enough to waddle across the // finish line! At a minimum, the CLI tool needs to be configured for our use case instead of // leaving the generation commands in the comments. +// NOTE The final down sampler should always use a flat pass band down to DC. The --terminal option +// for the PMR tool sets this low-ripple configuration. +// NOTE 16x group delay is about 1/8th of a 60FPS frame. If we buy more downsampling, we pay for it +// in time that faster attacking wavelets cannot buy back. Not that any transient can exist that +// outpaces the wavelength of the carrier when perceived by the listener without percussive onsets +// lighting up the screen. +// NEXT Document frequencies at usual input rate! I can't read 0.03123445 in a hurry!! -// $ cargo pmr lowpass --taps 25 --pass 0.125 --stop 0.375 --pass-guard 0.1 --stop-guard 0.2 -// --decimate 2` +/// Low pass filter. Odd. Symmetric. +pub(crate) struct Lowpass { + read_band: f32, + guard_band: f32, + /// Input samples consumed per output sample. + pub decimation: u32, + /// Raw weights. + pub taps: &'static [f32], +} + +impl Lowpass { + /// Use as an iteration count from the outside in. + pub const fn radius(&self) -> u32 { + (self.taps.len() as u32 - 1) / 2 + } + + /// Outward-in half of weights, center inclusive. Works as a zero-to-center or backwards + /// iterated end-to-center array of weights. + pub const fn folded(&self) -> &'static [f32] { + self.taps.split_at(self.radius() as usize + 1).0 + } + + /// Group delay in *input* samples. Linear phase, so it's just the center tap index. + pub const fn delay_in(&self) -> u32 { + self.radius() + } + + /// Group delay in *output* samples, post-decimation. + pub const fn delay_out(&self) -> u32 { + self.radius() / self.decimation + } + + /// Cutoff frequency for analysis. `rate_in` is the pre-decimation sample rate. Upper passband + /// edge in cycles/sample of the *input* rate. Main lobes of filters must not be centered above + /// this cutoff. + pub fn cutoff(&self, rate_in: f32) -> f32 { + self.read_band * rate_in + } + + /// Cutoff frequency beyond which folded noise begins to appear. `rate_in` is the + /// pre-decimation sample rate. Upper edge of the guarded (solver configuration) band in + /// cycles/sample of the *input* rate. Filter lobes that exceed this band will begin to see + /// folded noise. + pub fn guarded_cutoff(&self, rate_in: f32) -> f32 { + self.guard_band * rate_in + } +} + +// NOTE The first filter is intended to allow reads of the bottom half of the new Nyquist. Old +// Nyquist is half. New Nyquist is a quarter. Half of a quarter is an eighth. All subsequent +// filters provide read bands below half that down to the next filter. + +pub(crate) const DOWN_TWO: Lowpass = Lowpass { + read_band: 0.125, + guard_band: 0.1375, + decimation: 2, + taps: &DOWN_TWO_TAPS, +}; + +pub(crate) const DOWN_FOUR: Lowpass = Lowpass { + read_band: 0.0625, + guard_band: 0.06875, + decimation: 4, + taps: &DOWN_FOUR_TAPS, +}; + +pub(crate) const DOWN_EIGHT: Lowpass = Lowpass { + read_band: 0.03125, + guard_band: 0.034375, + decimation: 8, + taps: &DOWN_EIGHT_TAPS, +}; + +pub(crate) const DOWN_SIXTEEN: Lowpass = Lowpass { + read_band: 0.015625, + guard_band: 0.0171875, + decimation: 16, + taps: &DOWN_SIXTEEN_TAPS, +}; + +// cargo pmr lowpass --taps 21 --decimate 2 // // Optimal Lowpass FIR Weights: // ========================================================= -// Filter length: 25 -// Band frequencies are normalized to sample rate of 1.0 +// Filter length: 21 +// decimation: 2x +// output rate: 0.5000 (target Nyquist 0.2500) // -// passband: 0.0-0.1250 (guarded to 0.1500) -// stopband: 0.3750-0.5 (guarded from 0.3250) -// transition: 0.2500 wide, 0.1750 after guards +// All fractions in cycles/sample of the input rate (Nyquist = 0.5). +// passband: 0.0-0.1250 (guarded through 0.1375) +// shoulder: 0.1375-0.2500 (lands in unread band) +// fold: 0.2500-0.3625 (folds into unread band) +// stopband: 0.3625-0.5 (folds into passband) +// transition: 0.2250 wide +// weighting: non-terminal (DC ripple relaxed) // // Design Results // ========================================================= -// weighted error: 0.01381347 -// flatness: 0.00000611 -// iterations: 8 +// weighted error: 0.16595566 +// flatness: 0.00000000 +// iterations: 11 // // Gain Testing // ========================================================= -// deep pass band: 0.99978405 -// pass band: 0.99984044 -// new Nyquist: 0.32821527 -// upper passband fold mirror: 0.00007019 -// deep passband fold mirror: 0.00004710 -// stop band: 0.00007019 -// deep stop band: 0.00004710 -pub(crate) const DOWN_TWO: [f32; 25] = [ - f32::from_bits(0xba3d6162), // -7.224289002e-4 - f32::from_bits(0xba57a042), // -8.225479396e-4 - f32::from_bits(0x3b3e0b0c), // +2.899828367e-3 - f32::from_bits(0x3b8aa08c), // +4.230564460e-3 - f32::from_bits(0xbbec4190), // -7.209964097e-3 - f32::from_bits(0xbc5ecb44), // -1.359826699e-2 - f32::from_bits(0x3c5f764a), // +1.363904215e-2 - f32::from_bits(0x3d109501), // +3.529835120e-2 - f32::from_bits(0xbca9a000), // -2.070617676e-2 - f32::from_bits(0xbdb087ce), // -8.619652689e-2 - f32::from_bits(0x3cd89648), // +2.643884718e-2 - f32::from_bits(0x3e9f5183), // +3.111687601e-1 - f32::from_bits(0x3ef1619c), // +4.714478254e-1 - f32::from_bits(0x3e9f5183), // +3.111687601e-1 - f32::from_bits(0x3cd89648), // +2.643884718e-2 - f32::from_bits(0xbdb087ce), // -8.619652689e-2 - f32::from_bits(0xbca9a000), // -2.070617676e-2 - f32::from_bits(0x3d109501), // +3.529835120e-2 - f32::from_bits(0x3c5f764a), // +1.363904215e-2 - f32::from_bits(0xbc5ecb44), // -1.359826699e-2 - f32::from_bits(0xbbec4190), // -7.209964097e-3 - f32::from_bits(0x3b8aa08c), // +4.230564460e-3 - f32::from_bits(0x3b3e0b0c), // +2.899828367e-3 - f32::from_bits(0xba57a042), // -8.225479396e-4 - f32::from_bits(0xba3d6162), // -7.224289002e-4 +// deep pass band: 1.00052061 +0.00 dB +// pass band: 1.00157115 +0.01 dB +// new Nyquist: 0.16595566 -15.60 dB +// upper passband fold mirror: 0.00001381 -97.19 dB +// deep passband fold mirror: 0.00000825 -101.67 dB +// stop band: 0.00001660 -95.60 dB +// deep stop band: 0.00001462 -96.70 dB +// +const DOWN_TWO_TAPS: [f32; 21] = [ + f32::from_bits(0xba0fd4b3), // -5.486711743e-4 + f32::from_bits(0xbb7cc388), // -3.856869414e-3 + f32::from_bits(0xbc034f81), // -8.014560677e-3 + f32::from_bits(0xba0fc98c), // -5.485049915e-4 + f32::from_bits(0x3c9cc336), // +1.913605258e-2 + f32::from_bits(0x3c4a691d), // +1.235416252e-2 + f32::from_bits(0xbd37ed85), // -4.490425065e-2 + f32::from_bits(0xbd8ffdbe), // -7.030819356e-2 + f32::from_bits(0x3d71cd5b), // +5.903373286e-2 + f32::from_bits(0x3e99e477), // +3.005711734e-1 + f32::from_bits(0x3edaa466), // +4.270355105e-1 + f32::from_bits(0x3e99e477), // +3.005711734e-1 + f32::from_bits(0x3d71cd5b), // +5.903373286e-2 + f32::from_bits(0xbd8ffdbe), // -7.030819356e-2 + f32::from_bits(0xbd37ed85), // -4.490425065e-2 + f32::from_bits(0x3c4a691d), // +1.235416252e-2 + f32::from_bits(0x3c9cc336), // +1.913605258e-2 + f32::from_bits(0xba0fc98c), // -5.485049915e-4 + f32::from_bits(0xbc034f81), // -8.014560677e-3 + f32::from_bits(0xbb7cc388), // -3.856869414e-3 + f32::from_bits(0xba0fd4b3), // -5.486711743e-4 ]; -// $ cargo pmr lowpass --taps 49 --pass 0.0625 --stop 0.1875 --pass-guard 0.1 --stop-guard 0.2 -// --decimate 4 +// $ cargo pmr lowpass --taps 41 --decimate 4 +// +// Optimal Lowpass FIR Weights: +// ========================================================= +// Filter length: 41 +// decimation: 4x +// output rate: 0.2500 (target Nyquist 0.1250) +// +// All fractions in cycles/sample of the input rate (Nyquist = 0.5). +// passband: 0.0-0.0625 (guarded through 0.0688) +// shoulder: 0.0688-0.1250 (lands in unread band) +// fold: 0.1250-0.1812 (folds into unread band) +// stopband: 0.1812-0.5 (folds into passband) +// transition: 0.1125 wide +// weighting: non-terminal (DC ripple relaxed) +// +// Design Results +// ========================================================= +// weighted error: 0.18469634 +// flatness: 0.00000000 +// iterations: 13 // +// Gain Testing +// ========================================================= +// deep pass band: 1.00190087 +0.02 dB +// pass band: 1.00177958 +0.02 dB +// new Nyquist: 0.18469634 -14.67 dB +// upper passband fold mirror: 0.00001640 -95.70 dB +// deep passband fold mirror: 0.00001187 -98.51 dB +// stop band: 0.00001848 -94.67 dB +// deep stop band: 0.00001780 -94.99 dB +// +const DOWN_FOUR_TAPS: [f32; 41] = [ + f32::from_bits(0xb90a37e9), // -1.318153372e-4 + f32::from_bits(0xba136d02), // -5.623848410e-4 + f32::from_bits(0xbabb8a7e), // -1.430824166e-3 + f32::from_bits(0xbb29cf4f), // -2.591091907e-3 + f32::from_bits(0xbb608f86), // -3.426523414e-3 + f32::from_bits(0xbb409d97), // -2.939080587e-3 + f32::from_bits(0xb9919558), // -2.776782494e-4 + f32::from_bits(0x3b911e8d), // +4.428690765e-3 + f32::from_bits(0x3c1a5fcf), // +9.422256611e-3 + f32::from_bits(0x3c3c4087), // +1.148999389e-2 + f32::from_bits(0x3befb4d7), // +7.315258961e-3 + f32::from_bits(0xbb8d9335), // -4.320526961e-3 + f32::from_bits(0xbca85d3d), // -2.055227198e-2 + f32::from_bits(0xbd0b51dc), // -3.401361406e-2 + f32::from_bits(0xbd0eac8e), // -3.483252972e-2 + f32::from_bits(0xbc70c20e), // -1.469470374e-2 + f32::from_bits(0x3ceac9b0), // +2.866062522e-2 + f32::from_bits(0x3db5cb9b), // +8.876725286e-2 + f32::from_bits(0x3e1aecf8), // +1.512945890e-1 + f32::from_bits(0x3e4b5b7b), // +1.985911578e-1 + f32::from_bits(0x3e5d6659), // +2.162107378e-1 + f32::from_bits(0x3e4b5b7b), // +1.985911578e-1 + f32::from_bits(0x3e1aecf8), // +1.512945890e-1 + f32::from_bits(0x3db5cb9b), // +8.876725286e-2 + f32::from_bits(0x3ceac9b0), // +2.866062522e-2 + f32::from_bits(0xbc70c20e), // -1.469470374e-2 + f32::from_bits(0xbd0eac8e), // -3.483252972e-2 + f32::from_bits(0xbd0b51dc), // -3.401361406e-2 + f32::from_bits(0xbca85d3d), // -2.055227198e-2 + f32::from_bits(0xbb8d9335), // -4.320526961e-3 + f32::from_bits(0x3befb4d7), // +7.315258961e-3 + f32::from_bits(0x3c3c4087), // +1.148999389e-2 + f32::from_bits(0x3c1a5fcf), // +9.422256611e-3 + f32::from_bits(0x3b911e8d), // +4.428690765e-3 + f32::from_bits(0xb9919558), // -2.776782494e-4 + f32::from_bits(0xbb409d97), // -2.939080587e-3 + f32::from_bits(0xbb608f86), // -3.426523414e-3 + f32::from_bits(0xbb29cf4f), // -2.591091907e-3 + f32::from_bits(0xbabb8a7e), // -1.430824166e-3 + f32::from_bits(0xba136d02), // -5.623848410e-4 + f32::from_bits(0xb90a37e9), // -1.318153372e-4 +]; + +// $ cargo pmr lowpass --taps 81 --decimate 8 // Optimal Lowpass FIR Weights: // ========================================================= -// Filter length: 49 -// Band frequencies are normalized to sample rate of 1.0 +// Filter length: 81 +// decimation: 8x +// output rate: 0.1250 (target Nyquist 0.0625) // -// passband: 0.0-0.0625 (guarded to 0.0750) -// stopband: 0.1875-0.5 (guarded from 0.1625) -// transition: 0.1250 wide, 0.0875 after guards +// All fractions in cycles/sample of the input rate (Nyquist = 0.5). +// passband: 0.0-0.0312 (guarded through 0.0344) +// shoulder: 0.0344-0.0625 (lands in unread band) +// fold: 0.0625-0.0906 (folds into unread band) +// stopband: 0.0906-0.5 (folds into passband) +// transition: 0.0562 wide +// weighting: non-terminal (DC ripple relaxed) // // Design Results // ========================================================= -// weighted error: 0.02173785 +// weighted error: 0.20429698 // flatness: 0.00000000 -// iterations: 7 +// iterations: 18 // // Gain Testing // ========================================================= -// deep pass band: 0.99957645 -// pass band: 0.99975353 -// new Nyquist: 0.34572175 -// upper passband fold mirror: 0.00012299 -// deep passband fold mirror: 0.00004243 -// stop band: 0.00012299 -// deep stop band: 0.00008010 -pub(crate) const DOWN_FOUR: [f32; 49] = [ - f32::from_bits(0xb9353eda), // -1.728491916e-4 - f32::from_bits(0xb9bfb2f4), // -3.656368935e-4 - f32::from_bits(0xb9b24159), // -3.399949346e-4 - f32::from_bits(0x39248b21), // +1.569208835e-4 - f32::from_bits(0x3a939d4f), // +1.126209158e-3 - f32::from_bits(0x3b06a0cd), // +2.054262208e-3 - f32::from_bits(0x3b047459), // +2.021095017e-3 - f32::from_bits(0x398b70cd), // +2.659618913e-4 - f32::from_bits(0xbb448500), // -2.998650074e-3 - f32::from_bits(0xbbc8fdde), // -6.133778952e-3 - f32::from_bits(0xbbd72768), // -6.565976888e-3 - f32::from_bits(0xbb18e2ae), // -2.332847100e-3 - f32::from_bits(0x3bc6065e), // +6.043239497e-3 - f32::from_bits(0x3c701115), // +1.465251017e-2 - f32::from_bits(0x3c8e857b), // +1.739763282e-2 - f32::from_bits(0x3c18b7fa), // +9.321207181e-3 - f32::from_bits(0xbc1a0f04), // -9.402994066e-3 - f32::from_bits(0xbcfff290), // -3.124359250e-2 - f32::from_bits(0xbd2f8f0e), // -4.286103696e-2 - f32::from_bits(0xbcfac31c), // -3.061061352e-2 - f32::from_bits(0x3c482f84), // +1.221835986e-2 - f32::from_bits(0x3da424b8), // +8.014816046e-2 - f32::from_bits(0x3e1f3cde), // +1.555056274e-1 - f32::from_bits(0x3e5b9daa), // +2.144686282e-1 - f32::from_bits(0x3e7272f8), // +2.367666960e-1 - f32::from_bits(0x3e5b9daa), // +2.144686282e-1 - f32::from_bits(0x3e1f3cde), // +1.555056274e-1 - f32::from_bits(0x3da424b8), // +8.014816046e-2 - f32::from_bits(0x3c482f84), // +1.221835986e-2 - f32::from_bits(0xbcfac31c), // -3.061061352e-2 - f32::from_bits(0xbd2f8f0e), // -4.286103696e-2 - f32::from_bits(0xbcfff290), // -3.124359250e-2 - f32::from_bits(0xbc1a0f04), // -9.402994066e-3 - f32::from_bits(0x3c18b7fa), // +9.321207181e-3 - f32::from_bits(0x3c8e857b), // +1.739763282e-2 - f32::from_bits(0x3c701115), // +1.465251017e-2 - f32::from_bits(0x3bc6065e), // +6.043239497e-3 - f32::from_bits(0xbb18e2ae), // -2.332847100e-3 - f32::from_bits(0xbbd72768), // -6.565976888e-3 - f32::from_bits(0xbbc8fdde), // -6.133778952e-3 - f32::from_bits(0xbb448500), // -2.998650074e-3 - f32::from_bits(0x398b70cd), // +2.659618913e-4 - f32::from_bits(0x3b047459), // +2.021095017e-3 - f32::from_bits(0x3b06a0cd), // +2.054262208e-3 - f32::from_bits(0x3a939d4f), // +1.126209158e-3 - f32::from_bits(0x39248b21), // +1.569208835e-4 - f32::from_bits(0xb9b24159), // -3.399949346e-4 - f32::from_bits(0xb9bfb2f4), // -3.656368935e-4 - f32::from_bits(0xb9353eda), // -1.728491916e-4 +// deep pass band: 1.00164373 +0.01 dB +// pass band: 1.00198054 +0.02 dB +// new Nyquist: 0.20429697 -13.79 dB +// upper passband fold mirror: 0.00001973 -94.10 dB +// deep passband fold mirror: 0.00001806 -94.86 dB +// stop band: 0.00002044 -93.79 dB +// deep stop band: 0.00001192 -98.47 dB +// +const DOWN_EIGHT_TAPS: [f32; 81] = [ + f32::from_bits(0xb81d07f1), // -3.743911293e-5 + f32::from_bits(0xb8c14437), // -9.215663158e-5 + f32::from_bits(0xb9485f9a), // -1.910910069e-4 + f32::from_bits(0xb9b26e11), // -3.403281153e-4 + f32::from_bits(0xba0e0eae), // -5.419057561e-4 + f32::from_bits(0xba4e41a8), // -7.868059911e-4 + f32::from_bits(0xba89d0ee), // -1.051453641e-3 + f32::from_bits(0xbaa9e09a), // -1.296061324e-3 + f32::from_bits(0xbac02423), // -1.465920708e-3 + f32::from_bits(0xbac4246a), // -1.496446552e-3 + f32::from_bits(0xbaad4e5e), // -1.322220778e-3 + f32::from_bits(0xba692dab), // -8.895049687e-4 + f32::from_bits(0xb9331a9e), // -1.708068594e-4 + f32::from_bits(0x3a57272d), // +8.207436767e-4 + f32::from_bits(0x3b0462bb), // +2.020044951e-3 + f32::from_bits(0x3b5893e6), // +3.304713871e-3 + f32::from_bits(0x3b9367f1), // +4.498474766e-3 + f32::from_bits(0x3bb07453), // +5.384960677e-3 + f32::from_bits(0x3bbbd504), // +5.732180551e-3 + f32::from_bits(0x3bae8695), // +5.326102022e-3 + f32::from_bits(0x3b83656a), // +4.009892233e-3 + f32::from_bits(0x3ae1ee62), // +1.723718131e-3 + f32::from_bits(0xbabf818f), // -1.461075502e-3 + f32::from_bits(0xbbae51e2), // -5.319819786e-3 + f32::from_bits(0xbc1b282f), // -9.470029734e-3 + f32::from_bits(0xbc5b5ae2), // -1.338836737e-2 + f32::from_bits(0xbc86c28a), // -1.645018533e-2 + f32::from_bits(0xbc935eca), // -1.798953488e-2 + f32::from_bits(0xbc8e5479), // -1.737426408e-2 + f32::from_bits(0xbc66d0f9), // -1.408790890e-2 + f32::from_bits(0xbbffdbd1), // -7.808186579e-3 + f32::from_bits(0x3ac86038), // +1.528746448e-3 + f32::from_bits(0x3c604461), // +1.368817780e-2 + f32::from_bits(0x3ce66d7d), // +2.812837996e-2 + f32::from_bits(0x3d345648), // +4.402759671e-2 + f32::from_bits(0x3d772d31), // +6.034583226e-2 + f32::from_bits(0x3d9b79e1), // +7.591605932e-2 + f32::from_bits(0x3db768d1), // +8.955539018e-2 + f32::from_bits(0x3dcd2d0f), // +1.001835987e-1 + f32::from_bits(0x3ddb00ba), // +1.069349796e-1 + f32::from_bits(0x3ddfbe6e), // +1.092499346e-1 + f32::from_bits(0x3ddb00ba), // +1.069349796e-1 + f32::from_bits(0x3dcd2d0f), // +1.001835987e-1 + f32::from_bits(0x3db768d1), // +8.955539018e-2 + f32::from_bits(0x3d9b79e1), // +7.591605932e-2 + f32::from_bits(0x3d772d31), // +6.034583226e-2 + f32::from_bits(0x3d345648), // +4.402759671e-2 + f32::from_bits(0x3ce66d7d), // +2.812837996e-2 + f32::from_bits(0x3c604461), // +1.368817780e-2 + f32::from_bits(0x3ac86038), // +1.528746448e-3 + f32::from_bits(0xbbffdbd1), // -7.808186579e-3 + f32::from_bits(0xbc66d0f9), // -1.408790890e-2 + f32::from_bits(0xbc8e5479), // -1.737426408e-2 + f32::from_bits(0xbc935eca), // -1.798953488e-2 + f32::from_bits(0xbc86c28a), // -1.645018533e-2 + f32::from_bits(0xbc5b5ae2), // -1.338836737e-2 + f32::from_bits(0xbc1b282f), // -9.470029734e-3 + f32::from_bits(0xbbae51e2), // -5.319819786e-3 + f32::from_bits(0xbabf818f), // -1.461075502e-3 + f32::from_bits(0x3ae1ee62), // +1.723718131e-3 + f32::from_bits(0x3b83656a), // +4.009892233e-3 + f32::from_bits(0x3bae8695), // +5.326102022e-3 + f32::from_bits(0x3bbbd504), // +5.732180551e-3 + f32::from_bits(0x3bb07453), // +5.384960677e-3 + f32::from_bits(0x3b9367f1), // +4.498474766e-3 + f32::from_bits(0x3b5893e6), // +3.304713871e-3 + f32::from_bits(0x3b0462bb), // +2.020044951e-3 + f32::from_bits(0x3a57272d), // +8.207436767e-4 + f32::from_bits(0xb9331a9e), // -1.708068594e-4 + f32::from_bits(0xba692dab), // -8.895049687e-4 + f32::from_bits(0xbaad4e5e), // -1.322220778e-3 + f32::from_bits(0xbac4246a), // -1.496446552e-3 + f32::from_bits(0xbac02423), // -1.465920708e-3 + f32::from_bits(0xbaa9e09a), // -1.296061324e-3 + f32::from_bits(0xba89d0ee), // -1.051453641e-3 + f32::from_bits(0xba4e41a8), // -7.868059911e-4 + f32::from_bits(0xba0e0eae), // -5.419057561e-4 + f32::from_bits(0xb9b26e11), // -3.403281153e-4 + f32::from_bits(0xb9485f9a), // -1.910910069e-4 + f32::from_bits(0xb8c14437), // -9.215663158e-5 + f32::from_bits(0xb81d07f1), // -3.743911293e-5 ]; -// $ cargo pmr lowpass --taps 97 --pass 0.03125 --stop 0.09375 --pass-guard 0.1 --stop-guard 0.2 -// --decimate 8 +// $ cargo pmr lowpass --taps 161 --decimate 16 --terminal // // Optimal Lowpass FIR Weights: // ========================================================= -// Filter length: 97 -// Band frequencies are normalized to sample rate of 1.0 +// Filter length: 161 +// decimation: 16x +// output rate: 0.0625 (target Nyquist 0.0312) // -// passband: 0.0-0.0312 (guarded to 0.0375) -// stopband: 0.0938-0.5 (guarded from 0.0813) -// transition: 0.0625 wide, 0.0438 after guards +// All fractions in cycles/sample of the input rate (Nyquist = 0.5). +// passband: 0.0-0.0156 (guarded through 0.0172) +// shoulder: 0.0172-0.0312 (lands in unread band) +// fold: 0.0312-0.0453 (folds into unread band) +// stopband: 0.0453-0.5 (folds into passband) +// transition: 0.0281 wide +// weighting: terminal (flat down to DC) // // Design Results // ========================================================= -// weighted error: 0.02150317 -// flatness: 0.00000692 -// iterations: 8 +// weighted error: 0.22646222 +// flatness: 0.00000000 +// iterations: 14 // // Gain Testing // ========================================================= -// deep pass band: 0.99958384 -// pass band: 0.99975669 -// new Nyquist: 0.34913528 -// upper passband fold mirror: 0.00014459 -// deep passband fold mirror: 0.00005380 -// stop band: 0.00014459 -// deep stop band: 0.00006923 -pub(crate) const DOWN_EIGHT: [f32; 97] = [ - f32::from_bits(0xb8b975e0), // -8.843443356e-5 - f32::from_bits(0xb9145ef5), // -1.414975413e-4 - f32::from_bits(0xb93e3b79), // -1.814196730e-4 - f32::from_bits(0xb953d40f), // -2.020152606e-4 - f32::from_bits(0xb93a561a), // -1.777041762e-4 - f32::from_bits(0xb8c38469), // -9.322987898e-5 - f32::from_bits(0x3881b9a4), // +6.185777602e-5 - f32::from_bits(0x3993bdb4), // +2.817936474e-4 - f32::from_bits(0x3a0edf38), // +5.450132303e-4 - f32::from_bits(0x3a5460cb), // +8.101581479e-4 - f32::from_bits(0x3a85e08b), // +1.021401375e-3 - f32::from_bits(0x3a9202a4), // +1.113970298e-3 - f32::from_bits(0x3a869d08), // +1.027018763e-3 - f32::from_bits(0x3a3bc7f6), // +7.163280388e-4 - f32::from_bits(0x3931e25f), // +1.696436520e-4 - f32::from_bits(0xba18b7e5), // -5.825742264e-4 - f32::from_bits(0xbabf68b8), // -1.460335217e-3 - f32::from_bits(0xbb192993), // -2.337072743e-3 - f32::from_bits(0xbb47f40d), // -3.051045584e-3 - f32::from_bits(0xbb60a254), // -3.427644260e-3 - f32::from_bits(0xbb58d0b3), // -3.308337880e-3 - f32::from_bits(0xbb295f9b), // -2.584433882e-3 - f32::from_bits(0xbaa101b5), // -1.228383393e-3 - f32::from_bits(0x3a32bcc0), // +6.818287075e-4 - f32::from_bits(0x3b41827f), // +2.952724462e-3 - f32::from_bits(0x3bad1c5a), // +5.282920785e-3 - f32::from_bits(0x3beeeff9), // +7.291790564e-3 - f32::from_bits(0x3c0c5c34), // +8.566904813e-3 - f32::from_bits(0x3c0efb5b), // +8.726920001e-3 - f32::from_bits(0x3bf57720), // +7.491007447e-3 - f32::from_bits(0x3b9b8212), // +4.745730199e-3 - f32::from_bits(0x3a1c8bcb), // +5.971758510e-4 - f32::from_bits(0xbb96c542), // -4.601151682e-3 - f32::from_bits(0xbc27fe7f), // -1.025354769e-2 - f32::from_bits(0xbc7efd93), // -1.556338649e-2 - f32::from_bits(0xbca0a522), // -1.960999146e-2 - f32::from_bits(0xbcafbf0e), // -2.145340666e-2 - f32::from_bits(0xbca5efef), // -2.025601082e-2 - f32::from_bits(0xbc7c6408), // -1.540470868e-2 - f32::from_bits(0xbbd8d691), // -6.617375184e-3 - f32::from_bits(0x3bc41099), // +5.983423907e-3 - f32::from_bits(0x3cb2ed08), // +2.184154093e-2 - f32::from_bits(0x3d23cde2), // +3.999126703e-2 - f32::from_bits(0x3d72367d), // +5.913399532e-2 - f32::from_bits(0x3d9f4153), // +7.776131481e-2 - f32::from_bits(0x3dc125b4), // +9.431019425e-2 - f32::from_bits(0x3ddbd10c), // +1.073323190e-1 - f32::from_bits(0x3decdce0), // +1.156556606e-1 - f32::from_bits(0x3df2b9ac), // +1.185182035e-1 - f32::from_bits(0x3decdce0), // +1.156556606e-1 - f32::from_bits(0x3ddbd10c), // +1.073323190e-1 - f32::from_bits(0x3dc125b4), // +9.431019425e-2 - f32::from_bits(0x3d9f4153), // +7.776131481e-2 - f32::from_bits(0x3d72367d), // +5.913399532e-2 - f32::from_bits(0x3d23cde2), // +3.999126703e-2 - f32::from_bits(0x3cb2ed08), // +2.184154093e-2 - f32::from_bits(0x3bc41099), // +5.983423907e-3 - f32::from_bits(0xbbd8d691), // -6.617375184e-3 - f32::from_bits(0xbc7c6408), // -1.540470868e-2 - f32::from_bits(0xbca5efef), // -2.025601082e-2 - f32::from_bits(0xbcafbf0e), // -2.145340666e-2 - f32::from_bits(0xbca0a522), // -1.960999146e-2 - f32::from_bits(0xbc7efd93), // -1.556338649e-2 - f32::from_bits(0xbc27fe7f), // -1.025354769e-2 - f32::from_bits(0xbb96c542), // -4.601151682e-3 - f32::from_bits(0x3a1c8bcb), // +5.971758510e-4 - f32::from_bits(0x3b9b8212), // +4.745730199e-3 - f32::from_bits(0x3bf57720), // +7.491007447e-3 - f32::from_bits(0x3c0efb5b), // +8.726920001e-3 - f32::from_bits(0x3c0c5c34), // +8.566904813e-3 - f32::from_bits(0x3beeeff9), // +7.291790564e-3 - f32::from_bits(0x3bad1c5a), // +5.282920785e-3 - f32::from_bits(0x3b41827f), // +2.952724462e-3 - f32::from_bits(0x3a32bcc0), // +6.818287075e-4 - f32::from_bits(0xbaa101b5), // -1.228383393e-3 - f32::from_bits(0xbb295f9b), // -2.584433882e-3 - f32::from_bits(0xbb58d0b3), // -3.308337880e-3 - f32::from_bits(0xbb60a254), // -3.427644260e-3 - f32::from_bits(0xbb47f40d), // -3.051045584e-3 - f32::from_bits(0xbb192993), // -2.337072743e-3 - f32::from_bits(0xbabf68b8), // -1.460335217e-3 - f32::from_bits(0xba18b7e5), // -5.825742264e-4 - f32::from_bits(0x3931e25f), // +1.696436520e-4 - f32::from_bits(0x3a3bc7f6), // +7.163280388e-4 - f32::from_bits(0x3a869d08), // +1.027018763e-3 - f32::from_bits(0x3a9202a4), // +1.113970298e-3 - f32::from_bits(0x3a85e08b), // +1.021401375e-3 - f32::from_bits(0x3a5460cb), // +8.101581479e-4 - f32::from_bits(0x3a0edf38), // +5.450132303e-4 - f32::from_bits(0x3993bdb4), // +2.817936474e-4 - f32::from_bits(0x3881b9a4), // +6.185777602e-5 - f32::from_bits(0xb8c38469), // -9.322987898e-5 - f32::from_bits(0xb93a561a), // -1.777041762e-4 - f32::from_bits(0xb953d40f), // -2.020152606e-4 - f32::from_bits(0xb93e3b79), // -1.814196730e-4 - f32::from_bits(0xb9145ef5), // -1.414975413e-4 - f32::from_bits(0xb8b975e0), // -8.843443356e-5 +// deep pass band: 1.00080161 +0.01 dB +// pass band: 1.00250371 +0.02 dB +// new Nyquist: 0.22646221 -12.90 dB +// upper passband fold mirror: 0.00002263 -92.91 dB +// deep passband fold mirror: 0.00002265 -92.90 dB +// stop band: 0.00002264 -92.90 dB +// deep stop band: 0.00001941 -94.24 dB +// +const DOWN_SIXTEEN_TAPS: [f32; 161] = [ + f32::from_bits(0x362dc5e3), // +2.589419410e-6 + f32::from_bits(0xb7956429), // -1.780882485e-5 + f32::from_bits(0xb7c77ab3), // -2.377978490e-5 + f32::from_bits(0xb81e039a), // -3.767348971e-5 + f32::from_bits(0xb86e42c1), // -5.680579125e-5 + f32::from_bits(0xb8aaab15), // -8.138098201e-5 + f32::from_bits(0xb8ea813e), // -1.118206274e-4 + f32::from_bits(0xb91b96b5), // -1.483809465e-4 + f32::from_bits(0xb9485376), // -1.910457795e-4 + f32::from_bits(0xb97b1612), // -2.394544717e-4 + f32::from_bits(0xb9998837), // -2.928392205e-4 + f32::from_bits(0xb9b77c95), // -3.499730083e-4 + f32::from_bits(0xb9d680d4), // -4.091324518e-4 + f32::from_bits(0xb9f568b0), // -4.680803977e-4 + f32::from_bits(0xba0961ef), // -5.240728497e-4 + f32::from_bits(0xba167160), // -5.738940090e-4 + f32::from_bits(0xba20efa1), // -6.139223115e-4 + f32::from_bits(0xba27d520), // -6.402302533e-4 + f32::from_bits(0xba2a0ea2), // -6.487165811e-4 + f32::from_bits(0xba26885c), // -6.352716591e-4 + f32::from_bits(0xba1c3af4), // -5.959712435e-4 + f32::from_bits(0xba0a3a22), // -5.272944691e-4 + f32::from_bits(0xb9df88dc), // -4.263584269e-4 + f32::from_bits(0xb998a707), // -2.911614429e-4 + f32::from_bits(0xb8fd62a4), // -1.208235335e-4 + f32::from_bits(0x38b08d88), // +8.418696234e-5 + f32::from_bits(0x39a8be70), // +3.218534403e-4 + f32::from_bits(0x3a1a4243), // +5.884507555e-4 + f32::from_bits(0x3a6646f3), // +8.784375968e-4 + f32::from_bits(0x3a9b3e4d), // +1.184412860e-3 + f32::from_bits(0x3ac43bf4), // +1.497148070e-3 + f32::from_bits(0x3aecad4c), // +1.805701759e-3 + f32::from_bits(0x3b09784d), // +2.097624587e-3 + f32::from_bits(0x3b1a9db9), // +2.359254519e-3 + f32::from_bits(0x3b28d3d8), // +2.576103434e-3 + f32::from_bits(0x3b3321a0), // +2.733327448e-3 + f32::from_bits(0x3b389138), // +2.816272900e-3 + f32::from_bits(0x3b383a2c), // +2.811084501e-3 + f32::from_bits(0x3b314c54), // +2.705355175e-3 + f32::from_bits(0x3b231b21), // +2.488799626e-3 + f32::from_bits(0x3b0d28e2), // +2.153926063e-3 + f32::from_bits(0x3ade630a), // +1.696677180e-3 + f32::from_bits(0x3a9268db), // +1.117016538e-3 + f32::from_bits(0x39dbe6ba), // +4.194283974e-4 + f32::from_bits(0xb9cabd2e), // -3.866939223e-4 + f32::from_bits(0xbaa8a9c1), // -1.286797342e-3 + f32::from_bits(0xbb142e97), // -2.261077752e-3 + f32::from_bits(0xbb5741e0), // -3.284566104e-3 + f32::from_bits(0xbb8dcce2), // -4.327402450e-3 + f32::from_bits(0xbbaf7b91), // -5.355306435e-3 + f32::from_bits(0xbbcf6de7), // -6.330240052e-3 + f32::from_bits(0xbbec4c65), // -7.211255375e-3 + f32::from_bits(0xbc0257d7), // -7.955512963e-3 + f32::from_bits(0xbc0b9523), // -8.519443683e-3 + f32::from_bits(0xbc1129a7), // -8.860028349e-3 + f32::from_bits(0xbc1268f0), // -8.936151862e-3 + f32::from_bits(0xbc0eb463), // -8.709999733e-3 + f32::from_bits(0xbc05810d), // -8.148443885e-3 + f32::from_bits(0xbbecba66), // -7.224368863e-3 + f32::from_bits(0xbbc1eafb), // -5.917904433e-3 + f32::from_bits(0xbb8a32ed), // -4.217496607e-3 + f32::from_bits(0xbb0afcf7), // -2.120790770e-3 + f32::from_bits(0x39bf37fe), // +3.647207632e-4 + f32::from_bits(0x3b531cb9), // +3.221316496e-3 + f32::from_bits(0x3bd266e2), // +6.420955993e-3 + f32::from_bits(0x3c229e8b), // +9.925494902e-3 + f32::from_bits(0x3c604056), // +1.368721388e-2 + f32::from_bits(0x3c909601), // +1.764965244e-2 + f32::from_bits(0x3cb22a67), // +2.174873464e-2 + f32::from_bits(0x3cd449f1), // +2.591416426e-2 + f32::from_bits(0x3cf6578d), // +3.007104434e-2 + f32::from_bits(0x3d0bd827), // +3.414168581e-2 + f32::from_bits(0x3d1bd7bf), // +3.804754838e-2 + f32::from_bits(0x3d2ad969), // +4.171124473e-2 + f32::from_bits(0x3d388f5b), // +4.505858943e-2 + f32::from_bits(0x3d44b136), // +4.802056402e-2 + f32::from_bits(0x3d4efdfd), // +5.053519085e-2 + f32::from_bits(0x3d573dda), // +5.254922062e-2 + f32::from_bits(0x3d5d43af), // +5.401962623e-2 + f32::from_bits(0x3d60ee51), // +5.491477624e-2 + f32::from_bits(0x3d622977), // +5.521532521e-2 + f32::from_bits(0x3d60ee51), // +5.491477624e-2 + f32::from_bits(0x3d5d43af), // +5.401962623e-2 + f32::from_bits(0x3d573dda), // +5.254922062e-2 + f32::from_bits(0x3d4efdfd), // +5.053519085e-2 + f32::from_bits(0x3d44b136), // +4.802056402e-2 + f32::from_bits(0x3d388f5b), // +4.505858943e-2 + f32::from_bits(0x3d2ad969), // +4.171124473e-2 + f32::from_bits(0x3d1bd7bf), // +3.804754838e-2 + f32::from_bits(0x3d0bd827), // +3.414168581e-2 + f32::from_bits(0x3cf6578d), // +3.007104434e-2 + f32::from_bits(0x3cd449f1), // +2.591416426e-2 + f32::from_bits(0x3cb22a67), // +2.174873464e-2 + f32::from_bits(0x3c909601), // +1.764965244e-2 + f32::from_bits(0x3c604056), // +1.368721388e-2 + f32::from_bits(0x3c229e8b), // +9.925494902e-3 + f32::from_bits(0x3bd266e2), // +6.420955993e-3 + f32::from_bits(0x3b531cb9), // +3.221316496e-3 + f32::from_bits(0x39bf37fe), // +3.647207632e-4 + f32::from_bits(0xbb0afcf7), // -2.120790770e-3 + f32::from_bits(0xbb8a32ed), // -4.217496607e-3 + f32::from_bits(0xbbc1eafb), // -5.917904433e-3 + f32::from_bits(0xbbecba66), // -7.224368863e-3 + f32::from_bits(0xbc05810d), // -8.148443885e-3 + f32::from_bits(0xbc0eb463), // -8.709999733e-3 + f32::from_bits(0xbc1268f0), // -8.936151862e-3 + f32::from_bits(0xbc1129a7), // -8.860028349e-3 + f32::from_bits(0xbc0b9523), // -8.519443683e-3 + f32::from_bits(0xbc0257d7), // -7.955512963e-3 + f32::from_bits(0xbbec4c65), // -7.211255375e-3 + f32::from_bits(0xbbcf6de7), // -6.330240052e-3 + f32::from_bits(0xbbaf7b91), // -5.355306435e-3 + f32::from_bits(0xbb8dcce2), // -4.327402450e-3 + f32::from_bits(0xbb5741e0), // -3.284566104e-3 + f32::from_bits(0xbb142e97), // -2.261077752e-3 + f32::from_bits(0xbaa8a9c1), // -1.286797342e-3 + f32::from_bits(0xb9cabd2e), // -3.866939223e-4 + f32::from_bits(0x39dbe6ba), // +4.194283974e-4 + f32::from_bits(0x3a9268db), // +1.117016538e-3 + f32::from_bits(0x3ade630a), // +1.696677180e-3 + f32::from_bits(0x3b0d28e2), // +2.153926063e-3 + f32::from_bits(0x3b231b21), // +2.488799626e-3 + f32::from_bits(0x3b314c54), // +2.705355175e-3 + f32::from_bits(0x3b383a2c), // +2.811084501e-3 + f32::from_bits(0x3b389138), // +2.816272900e-3 + f32::from_bits(0x3b3321a0), // +2.733327448e-3 + f32::from_bits(0x3b28d3d8), // +2.576103434e-3 + f32::from_bits(0x3b1a9db9), // +2.359254519e-3 + f32::from_bits(0x3b09784d), // +2.097624587e-3 + f32::from_bits(0x3aecad4c), // +1.805701759e-3 + f32::from_bits(0x3ac43bf4), // +1.497148070e-3 + f32::from_bits(0x3a9b3e4d), // +1.184412860e-3 + f32::from_bits(0x3a6646f3), // +8.784375968e-4 + f32::from_bits(0x3a1a4243), // +5.884507555e-4 + f32::from_bits(0x39a8be70), // +3.218534403e-4 + f32::from_bits(0x38b08d88), // +8.418696234e-5 + f32::from_bits(0xb8fd62a4), // -1.208235335e-4 + f32::from_bits(0xb998a707), // -2.911614429e-4 + f32::from_bits(0xb9df88dc), // -4.263584269e-4 + f32::from_bits(0xba0a3a22), // -5.272944691e-4 + f32::from_bits(0xba1c3af4), // -5.959712435e-4 + f32::from_bits(0xba26885c), // -6.352716591e-4 + f32::from_bits(0xba2a0ea2), // -6.487165811e-4 + f32::from_bits(0xba27d520), // -6.402302533e-4 + f32::from_bits(0xba20efa1), // -6.139223115e-4 + f32::from_bits(0xba167160), // -5.738940090e-4 + f32::from_bits(0xba0961ef), // -5.240728497e-4 + f32::from_bits(0xb9f568b0), // -4.680803977e-4 + f32::from_bits(0xb9d680d4), // -4.091324518e-4 + f32::from_bits(0xb9b77c95), // -3.499730083e-4 + f32::from_bits(0xb9998837), // -2.928392205e-4 + f32::from_bits(0xb97b1612), // -2.394544717e-4 + f32::from_bits(0xb9485376), // -1.910457795e-4 + f32::from_bits(0xb91b96b5), // -1.483809465e-4 + f32::from_bits(0xb8ea813e), // -1.118206274e-4 + f32::from_bits(0xb8aaab15), // -8.138098201e-5 + f32::from_bits(0xb86e42c1), // -5.680579125e-5 + f32::from_bits(0xb81e039a), // -3.767348971e-5 + f32::from_bits(0xb7c77ab3), // -2.377978490e-5 + f32::from_bits(0xb7956429), // -1.780882485e-5 + f32::from_bits(0x362dc5e3), // +2.589419410e-6 ]; diff --git a/mutate-visualizer/src/audio/mod.rs b/mutate-visualizer/src/audio/mod.rs index 2fc899b9..c6a1f16b 100644 --- a/mutate-visualizer/src/audio/mod.rs +++ b/mutate-visualizer/src/audio/mod.rs @@ -11,29 +11,21 @@ //! //! Audio and video will basically never tick on the same clock or at the same rate, and VRR //! displays and other frontends will just further expose the independence. The tracking & slew and -//! re-sampling are all unavoidable and consumers **must** be built these dynamics in mind. +//! re-sampling are all unavoidable and consumers **must** be built with these dynamics in mind. //! //! Eventually the audio side will become a runtime component that can drive an audio graph and -//! manage pushing values to reactive dependents (pointer swaps, read/write heads etc). - -// DEBT Reactive updates. Keep modularizing audio pipelines for downstreams. Dispatching a bunch -// of IIRs and other audio processing will parallelize easily and the output addresses can just be -// exposed to video pipelines without dynamic resolution for now. -// NEXT Extend vk::Device for things that don't require the wrapped Device. Then &Device grows -// those methods via Deref. -// MAYBE get rid of fences on most submissions? -// NOTE resource reactivity for audio pipelines is interesting. The signal to resize the screen for -// example might trigger resource recreation. The resource change notifications then need to be -// sent to the thread and finally pulled by.. the caller during the callback. -// NEXT automatically promote u32 -> UInt32 and newtypes thereof -// XXX DeviceAddress and vk::DeviceAddress are too redundant. +//! manage pushing values to reactive dependents (pointer swaps, parameter pull, +//! read/write heads etc). + // NOTE Like the visualizer, support for a dynamic set of audio pipelines is necessary. Lacking -// that, the RMS pipeline was fully removed to add the DFT. See blame. We would like support for -// mixtures of pipelines, and the resource runtime will need to orchestrate this. +// that, for example, the RMS pipeline was fully removed to add the CWT pipeline. We can't really +// turn them on and off at runtime. See blame. We would like support for mixtures of pipelines, +// and the resource runtime will need to orchestrate this. -pub mod dft; +pub mod cwt; pub mod downsample; pub mod plan; +pub mod spectrum; use std::sync::{ atomic::{AtomicBool, Ordering}, @@ -42,17 +34,20 @@ use std::sync::{ use ash::vk; use mutate_lib::{self as utate, audio, prelude::*}; +use utate::audio::timing::AudioTiming; pub struct CallbackResources { /// How far have we read into the data so far? // NOTE unbuffered, same clock consume_head: u64, + dead: AtomicBool, // Hacky tombstone to stop dispatches faster. + last_consumed: u32, + outputs: Arc>>, pool_ring: PoolRing, - dft: dft::Dft, + + cwt: cwt::Cwt, + spectrum: spectrum::Spectrum, downsample: downsample::Downsample, - outputs: Arc>>, - last_consumed: u32, - dead: AtomicBool, // Hacky tombstone to stop dispatches faster. } /// Until some kind of reactive parameter design is done, cram outputs onto this struct so that each @@ -60,17 +55,19 @@ pub struct CallbackResources { /// parameters onto an input structure for the command recorder to pull. #[derive(Clone, Debug)] pub struct AudioOutputs { - pub dft: dft::DftOutput, + pub cwt: DeviceAddress, // CwtOutput struct in the header. pub downsample: downsample::DownsampleOutput, + pub spectrum: spectrum::Output, // Dynamic range gain factor location (on device) // Timing data for downstream buffered tracking - // XXX isn't the timing daata available for clone? + pub timing: Option, + pub ready: WaitValue, } pub struct Audio { context: AudioContext, resources: *mut CallbackResources, - pub audio_import: AudioImport<2>, + pub audio_import: AudioImport, // NOTE suppose we already have the resources runtime ready. The Option goes away because this // is a dependency for the downstream renderer. They don't want to care if the upstream is // running. No input, don't call them. The Arc goes away because the runtime owns the values. @@ -78,8 +75,6 @@ pub struct Audio { pub outputs: Arc>>, } -const EMPTY_SPAN: DeviceSpan = DeviceSpan { base: 0, len: 0 }; - impl Audio { // NOTE all of the audio processing can happen in compute queues, but the resources for hand-off // to graphics for presentation will need concurrent access since the ring buffers cannot be @@ -110,9 +105,6 @@ impl Audio { let choice = first_choices.remove(choice_idx); let rx = context.connect(&choice, "µTate")?; - // Allocate the ring so that callback and later the DeviceImport - let (buffer, ring_layout) = AudioImport::<2>::allocate(device, 4096)?; - // MAYBE IIRC Untorn is right type here. Consumer only wants the latest value and ticks // independently, so best-effort on-time delivery is fine. In any case, it's a short lock // to read for now. Option is only because the RingLayout is currently only known after the @@ -124,39 +116,45 @@ impl Audio { let callback_outputs = outputs.clone(); let pool_ring = PoolRing::new(device, &callback_queue)?; - let downsample = downsample::Downsample::new(device, ring_layout)?; - let dft = dft::Dft::new(device, downsample.level_layout(2))?; + // DEBT Made up channel and sample count. Probably want to nail it to the AudioChoice, but + // maybe keep it on the callback to support pipewire re-negotiation. + let downsample = downsample::Downsample::new(device, 2, 48000)?; + // XXX we need levels from the downs sampler... + let cwt = cwt::Cwt::new(device, downsample.view())?; + let spectrum = spectrum::Spectrum::new(device, cwt.view())?; + let resources = Box::into_raw(Box::new(CallbackResources { consume_head: 0, + dead: false.into(), + last_consumed: 0, + outputs: outputs.clone(), pool_ring, - dft, + + cwt, downsample, - outputs: outputs.clone(), - last_consumed: 0, - dead: false.into(), + spectrum, })); // Pass resources address into the callback. Ownership and cleanup remain with us. let addr = resources as usize; - let on_flush = move |state: &utate::audio::import::DeviceRingView<2>| { - // Drive the audio pipeline (◕‿◕)♡ + let on_flush = move |state: &utate::audio::import::DeviceAudioView| { + // Just re-bindings of callback thread local data. let outputs = &callback_outputs; let device = &callback_device; - let timing = state.timing; - let res = unsafe { &mut *(addr as *mut CallbackResources) }; + if state.read_count() == 0 { + println!("warning: DeviceAudioView contained no fresh samples."); + return Ok(0); + } + + let res = unsafe { &mut *(addr as *mut CallbackResources) }; if res.dead.load(Ordering::Acquire) { // Stop advancing, stop dispatching, tell pipewire upstream it's okay to reclaim // everything. - return Ok(state.occupied_len()); + return Ok(state.read_count()); } - let regions = state.regions_since(res.consume_head); - if regions[0].occupied_len() == 0 { - return Ok(0); - } - let layout = state.ring_layout; - + // Drive the audio pipeline (◕‿◕)♡ let (pool, intent) = match res.pool_ring.acquire(device, 16_000_000_000) { Ok(acquired) => acquired, Err(e) => { @@ -169,50 +167,35 @@ impl Audio { let downsample::DownsampleDispatch { output: downsample_out, - ready: downsample_ready, consumed: downsample_consumed, + .. } = res.downsample.dispatch(device, &cb, state)?; - let downsample_previous = downsample_ready.predecessor(); - let dft_out_wait = vk::MemoryBarrier2::default() + // DEBT 🐷 + let barrier = vk::MemoryBarrier2::default() .src_stage_mask(vk::PipelineStageFlags2::COMPUTE_SHADER) .src_access_mask(vk::AccessFlags2::SHADER_WRITE) .dst_stage_mask(vk::PipelineStageFlags2::COMPUTE_SHADER) .dst_access_mask(vk::AccessFlags2::SHADER_READ); - let barriers = [dft_out_wait]; + let barriers = [barrier]; let dep = vk::DependencyInfo::default().memory_barriers(&barriers); unsafe { device.cmd_pipeline_barrier2(**&cb, &dep) }; - // TODO get downsample outputs for the DFT + let cwt::Dispatch { output: cwt_out } = + res.cwt.dispatch(device, &cb, &downsample_out)?; - let dft::DftDispatch { - consumed: dft_consumed, - ready: dft_ready, - output: dft_out, - } = res.dft.dispatch(device, &cb, &downsample_out)?; - let dft_previous = dft_ready.predecessor(); + unsafe { device.cmd_pipeline_barrier2(**&cb, &dep) }; + let ready = intent.wait_value(); - // DFT dependents need this barrier. The need is graph-detected later. - let dft_out_wait = vk::MemoryBarrier2::default() - .src_stage_mask(vk::PipelineStageFlags2::COMPUTE_SHADER) - .src_access_mask(vk::AccessFlags2::SHADER_WRITE) - .dst_stage_mask(vk::PipelineStageFlags2::COMPUTE_SHADER) - .dst_access_mask(vk::AccessFlags2::SHADER_READ); - let barriers = [dft_out_wait]; - let dep = vk::DependencyInfo::default().memory_barriers(&barriers); unsafe { device.cmd_pipeline_barrier2(**&cb, &dep) }; // NEXT use shared on outputs and wait on the correct semaphores let done = cb.end(device)?; callback_queue .submission() - .wait(downsample_previous, vk::PipelineStageFlags2::COMPUTE_SHADER) - .wait(dft_previous, vk::PipelineStageFlags2::COMPUTE_SHADER) .execute(done) // XXX Rip out the individual semaphores. Most consumers will prefer to see one // consistent audio graph. - .signal(downsample_ready, vk::PipelineStageFlags2::COMPUTE_SHADER) - .signal(dft_ready, vk::PipelineStageFlags2::COMPUTE_SHADER) .signal(intent, vk::PipelineStageFlags2::COMPUTE_SHADER) .submit(&callback_device, vk::Fence::null())?; @@ -220,8 +203,11 @@ impl Audio { res.consume_head = state.write_head; *outputs.lock().unwrap() = Some(AudioOutputs { - dft: dft_out, + cwt: cwt_out, downsample: downsample_out, + timing: state.timing, + ready, + spectrum: todo!(), }); // XXX Super hack here, but consistent. We should catch up a bit differently to try and @@ -238,14 +224,11 @@ impl Audio { // Ok(last) // } - println!("downsample consumed: {:?}", downsample_consumed); - println!("occupied len: {:?}", state.occupied_len()); - Ok(state.occupied_len()) + Ok(state.read_count()) }; - // Create the import, which fires the callback. - let audio_import = - AudioImport::with_allocation(device, rx, (buffer, ring_layout), on_flush)?; + // Create the import, which will begin firing the callback. + let audio_import = AudioImport::new(device, rx, 4096, on_flush)?; Ok(Self { context, @@ -273,7 +256,7 @@ impl Audio { resources.pool_ring.drain(device, 1_000_000_000)?; resources.pool_ring.destroy(device); resources.downsample.destroy(device); - resources.dft.destroy(device); + resources.cwt.destroy(device); // context has no vulkan resources and may just drop. Ok(()) } diff --git a/mutate-visualizer/src/audio/spectrum.rs b/mutate-visualizer/src/audio/spectrum.rs new file mode 100644 index 00000000..7cea7145 --- /dev/null +++ b/mutate-visualizer/src/audio/spectrum.rs @@ -0,0 +1,144 @@ +// Copyright 2026 The MuTate Contributors +// SPDX-License-Identifier: MIT OR Apache-2.0 + +//! # Spectrograph +//! +//! > We sincerely apologize that some funds were temporarily located in places other than the +//! > places where those funds were intended to be located. +//! > +//! > - Samuel Benjamin Bankman-Fried +//! +//! The raw output of the CWT after an audio tick is essentially a scattered data set. The purpose +//! of this module is to gather that scatter. Readers want something closer to a spectrogram, a +//! ring buffer of more easily readable, time-aligned, de-messed-up output. I'm getting dyslexia +//! just thinking about this data. +//! +//! ## Input +//! +//! - The bin ring buffer offsets. +//! - Bin table for tweaking reads across the bank. +//! +//! ## Output +//! +//! - Ring buffer per channel +//! - Rows correspond to time +//! - Columns correspond to bins +//! - Datum is a complex value...maybe magnitude and phase. We'll see how complex it all is. + +use ash::vk; + +use mutate_lib::vulkan::resource::retired::RawHandle; +use mutate_lib::{self as utate, prelude::*}; + +use super::cwt; +use super::plan; + +/// Output data location & geometry for consumers +#[derive(Clone, Copy, Debug)] +pub struct Output { + pub base: DeviceAddress, + pub channel_count: u32, + pub channel_slots: u32, + pub write_head: u64, + + // XXX compile + pub ring_width: u32, +} + +impl Output { + pub fn bins(&self) -> u32 { + 0 + } + + pub fn slots(&self) -> u32 { + 0 + } +} + +struct Config {} + +#[compute_pipeline( + compute = stage!("audio/spectrum", Compute, c"main"), + push = push!(PushConstants { + static_base: DeviceAddress, + }), +)] +pub struct Pipeline; + +pub struct Spectrum { + allocation: MappedAllocation, + static_base: DeviceAddress, + output_base: DeviceAddress, + pipeline: ComputePipeline, + write_head: u64, +} + +impl Spectrum { + pub fn new(device: &Device, input: cwt::Output) -> Result { + // XXX Get it from the input + let channels = 2; + + let mut c = plan::Cursor::default(); + let config_offset = c.push::(1); + let static_bytes = c.align_to(256); + + let mut c = plan::Cursor::default(); + let dynamic_bytes = c.len(); + + // XXX padded to avoid dying + let mut allocation = + MappedAllocation::::new(device, (static_bytes + dynamic_bytes + 128) as usize)?; + let base = allocation.device_address(device)?; + let static_base: DeviceAddress = base.into(); + let output_base: DeviceAddress = (base + static_bytes as u64).into(); + + let (stat, _dynam) = allocation + .as_mut_slice() + .split_at_mut(static_bytes as usize); + plan::put(stat, config_offset, Config {}); + + Ok(Self { + allocation, + pipeline: ComputePipeline::::new(device)?, + + static_base, + output_base, + write_head: 0, + }) + } + + pub fn dispatch( + &mut self, + device: &ash::Device, + cb: &RecordingBuffer, + input: &cwt::Output, + ) -> Result { + // let count = self.ready_outputs(input.write_head); + + let constants = PushConstants { + static_base: self.static_base, /* slots from head */ + }; + self.pipeline.push(device, **cb, &constants); + + let count: u32 = 1; + unsafe { + device.cmd_bind_pipeline(**cb, vk::PipelineBindPoint::COMPUTE, *self.pipeline); + device.cmd_dispatch(**cb, count.div_ceil(256), 1, 2); + } + + todo!() + } + + pub fn destroy(self, device: &Device) { + device.deletion_queue.push(self.allocation.buffer); + device.deletion_queue.push(self.allocation.memory); + device.deletion_queue.push(self.pipeline.into_raw()); + } + + // XXX state poll for setting up other things. + + /// Backpressure contract to upstream. + pub fn retain_floor(&self) -> u64 { + todo!() + } +} diff --git a/mutate-visualizer/src/main.rs b/mutate-visualizer/src/main.rs index d213ea4f..031f1d5d 100644 --- a/mutate-visualizer/src/main.rs +++ b/mutate-visualizer/src/main.rs @@ -1,13 +1,30 @@ // Copyright 2026 The MuTate Contributors // SPDX-License-Identifier: MIT OR Apache-2.0 -//! Visualizer +//! # Visualizer +//! +//! > Get your own rally +//! > +//! > - Master Splinter +//! +//! See the CONTRIBUTING guide to find starting points. The visualizer bin is but one possible +//! frontend for mutate-lib, which ships the GPU audio import and on-GPU spectrogram, the +//! elementary starting input for most frontends. See the example app for a more minimal use of the +//! Vulkan engine. //! //! - [`WindowContext`] owns per-window resources and lifecycle //! - [`ActiveApp`] is a variant of [`AppState`] that encapsulates resources that live within the //! resumed lifecycle segments of the application. //! - [`MutateApp`] owns the longest lived resources such as the Vulkan context and audio input //! stream. +//! +//! If you would like support to implement or modify a visualization, get in touch. + +// NEXT The minimal example is already closer to the proper threading structure. That work need +// propagation into this crate + +// Keep noise down by default. Re-enable in dirty trees as helpful. +#![allow(warnings)] mod audio; mod video; @@ -65,7 +82,7 @@ impl WindowContext { audio_outputs: Arc>>, ) -> Self { // XXX create the present ring and clone the queue to audio farther upstream? - let present_ring = PresentRing::new(device, instance, &surface).unwrap(); + let present_ring = PresentRing::new(instance, device, &surface).unwrap(); let mut renderer = video::verticlysm::Verticlysm::new(device); renderer.provision(device, surface.extent()).unwrap(); Self { diff --git a/mutate-visualizer/src/video/mod.rs b/mutate-visualizer/src/video/mod.rs index c09718e5..ebf509a8 100644 --- a/mutate-visualizer/src/video/mod.rs +++ b/mutate-visualizer/src/video/mod.rs @@ -1,9 +1,25 @@ // Copyright 2026 The MuTate Contributors // SPDX-License-Identifier: MIT OR Apache-2.0 -//! # Video Nodes +//! # Video //! -//! Drawing and presentation go here. +//! Things that draw things. +//! +//! To any following along, the intended development path ahead is complex and will require +//! continuous application of strangler fig pattern. Aggressive, haphazard development is not only +//! welcome, but a requirement. +//! +//! The intended path is to support loading libraries (plugins) that describe how a runtime can call +//! into them to set up drawing methods or load resources. Visualizations that land in the core +//! will be curated to catalog techniques and establish the APIs under maintenance. +//! +//! The natural path forward: +//! +//! - visualizations can be toggled at +//! - toggle at runtime +//! - composing steps +//! - transitions between different graphs +//! - runtime modulation of steps pub mod pulse; pub mod ring; diff --git a/mutate-visualizer/src/video/verticlysm.rs b/mutate-visualizer/src/video/verticlysm.rs index 4f27968f..10850da1 100644 --- a/mutate-visualizer/src/video/verticlysm.rs +++ b/mutate-visualizer/src/video/verticlysm.rs @@ -3,7 +3,7 @@ //! # Verticlysm //! -//! Draws DFT with bins mapped horizontally, creating a vertical pattern. Left interpolates from +//! Draws spectrum with bins mapped horizontally, creating a vertical pattern. Left interpolates from //! bottom to top. Right interpolates from top to bottom. Intensity controls both initial //! brightness and length of interpolation along the screen's vertical axis. Interpolates bins and //! the 240Hz output with phase-aware tracking of the input stream. @@ -19,16 +19,17 @@ use crate::audio; // Input channel rings and geometry. pub left_channel: DeviceAddress, pub right_channel: DeviceAddress, - /// Number of DFT bins - pub input_height: UInt, - /// Ring columns. Time. Always PoT. - pub input_width: UInt, + /// Number of spectrum bins + pub input_bins: UInt, + /// Ring slots. Time. Always PoT. + pub input_slots: UInt, // The time slice being read. pub beg_col: UInt, pub beg_phase: Float, pub span: Float, + // XXX after spectrum is ready // pub gain: DeviceAddress, /// Output buffer @@ -78,7 +79,7 @@ impl Verticlysm { audio_outputs: &audio::AudioOutputs, ) { let extent = acquired_image.extent; - let dft = &audio_outputs.dft; + let spectrum = &audio_outputs.spectrum; // XXX argument order (reverse cb & device) self.output @@ -86,7 +87,8 @@ impl Verticlysm { .unwrap() .barrier_compute_pre(&cb, device); - dft.data_ready.wait(device, 1_000_000_000).unwrap(); + // XXX put a sempaphore on AudioOutputs + // spectrum.ready.wait(device, 1_000_000_000).unwrap(); let pre = vk::MemoryBarrier2::default() .src_stage_mask(vk::PipelineStageFlags2::COPY | vk::PipelineStageFlags2::COMPUTE_SHADER) @@ -101,7 +103,7 @@ impl Verticlysm { let dep = vk::DependencyInfo::default().memory_barriers(&pre_barriers); unsafe { device.cmd_pipeline_barrier2(**cb, &dep) }; - let width = dft.ring_width; + let width = spectrum.ring_width; debug_assert!(width.is_power_of_two()); let mask = width as u64 - 1; @@ -110,7 +112,7 @@ impl Verticlysm { // is exactly the set of columns the device has committed. `beg_phase` is // pinned to zero and the shader's interpolation degenerates to nearest-column. const TARGET_SPAN: u64 = 4; - let end = dft.write_head; + let end = spectrum.write_head; // Never reach past what's been written, and leave one column of slack so we // can't alias the column the device is currently accumulating into. @@ -123,11 +125,13 @@ impl Verticlysm { let beg_phase = 0.0f32; let push = VerticlysmPushConstants { - left_channel: dft.channels[0].into(), - right_channel: dft.channels[1].into(), + // XXX Channels completely hosed + left_channel: DeviceAddress::NULL, + right_channel: DeviceAddress::NULL, + + input_bins: spectrum.bins().into(), + input_slots: spectrum.slots().into(), - input_height: dft.ring_height.into(), - input_width: width.into(), beg_col: (beg_col as u32).into(), beg_phase: beg_phase.into(), span: (span as f32).into(), @@ -169,7 +173,7 @@ impl Verticlysm { // Seems like we will need to build our own submission harness. That sucks, but it will // work better. During the multithreaded switcharoo we can get that done. Just hope it's // on time =D - let ready = &dft.data_ready; + // XXX Go return the normal semaphore } pub fn destroy(self, device: &Device) -> Result<(), utate::MutateError> {