waveforms 3.5.1__tar.gz → 3.7.0__tar.gz

{waveforms-3.5.1/waveforms.egg-info → waveforms-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: waveforms
-Version: 3.5.1
+Version: 3.7.0
 Summary: Edit waveforms used in experiment
 Author-email: feihoo87 <feihoo87@gmail.com>
 Maintainer-email: feihoo87 <feihoo87@gmail.com>
@@ -202,21 +202,51 @@ uses the same final limits. The filter state continues from the unclipped
 filtered signal across chunks. DAC `full_scale` controls integer conversion
 and saturation separately from these amplitude limits.
 
-Real-coefficient SOS filters (`filters=(sos, initial)`) run in the C core for
-float64 and complex128 signals. This stage subtracts the baseline `initial`,
-applies the cascade, restores the baseline, and applies the final limits.
+`filters` is a `defaultdict(float)` mapping exponential cascade time constants
+`tau` (in seconds) to amplitudes `amp`, independent of the sampling clock:
+
+```python
+stack.filters[100e-9] += 0.12
+stack.filters[2e-6] += -0.04
+samples = stack.sample(sample_rate=2_400_000_000)
+unfiltered = stack.sample(filters={})  # bypass predistortion for this call
+```
+
+The parameters describe cascade stages, not a parallel sum of exponential
+terms. Sampling uses `exp_decay_filter_from_cascade` followed by
+`exp_decay_filter(..., inv=True, output="sos")` at the actual sample rate:
+filtering defaults to **predistortion**. Coefficients are cached by parameter
+values and sample rate; changing an amplitude or the clock takes effect on the
+next sampling call. Only the parameters are saved by pickle, not cached SOS
+coefficients. Assign a mapping to replace them, or `None` to clear them. The old
+`(sos, initial)` representation is no longer accepted.
+
+The initial level is the first sample **after nonlinear mapping**, before
+output limiting: the system is assumed to have held that level indefinitely
+before playback. This stage subtracts that baseline, applies the inverse
+filter, restores the baseline, and applies the final limits. Chunked sampling
+retains both the initial level and the unclipped filter state across chunks;
+complex signals use the first I and Q values independently.
+
+SOS filtering runs in the C core for float64 and complex128 signals.
 Real int16/int32 output is quantized in the same stage, without allocating a
 full filtered floating-point buffer. Float output can reuse the sampled
 buffer. A small fixed scratch buffer keeps filtering and conversion local;
-waveform evaluation and nonlinear mapping still precede this stage. Complex
-coefficients and extended precision retain the SciPy implementation.
+waveform evaluation and nonlinear mapping still precede this stage.
 `sample_iq()` still converts the filtered complex result into separate I/Q
 output arrays. See [the SOS benchmark](benchmarks/sos_filter.md).
 
-Calling `waveform(t)` directly evaluates with amplitude limits but without
-nonlinear calibration or filtering. Sampling evaluates the underlying signal
-without limits before applying its processing chain. Limits are sampling
-metadata preserved by pickle, not part of the raw WNF4/WNS4 binary blocks.
+Calling `waveform(t)` applies waveform/event accumulation, the object's
+nonlinear mapping, and then its own amplitude limits. It does not apply SOS
+filters or DAC quantization. Stacks and complex wrappers use raw child values;
+child maps and limits do not affect the parent's processing chain. Thus direct
+evaluation and unfiltered floating-point sampling have the same processing
+semantics on the same time grid, subject to floating-point rounding. With
+`out=` and `accumulate=True`, the processed contribution is added to the
+existing buffer without mapping or limiting its previous contents. Sampling
+starts from raw values so mapping and limits are each applied only once, with
+SOS filtering between them when configured. Maps and limits are metadata
+preserved by pickle, not part of the raw WNF4/WNS4 binary blocks.
 
 ## Reporting Issues
 Please report all issues [on github](https://github.com/feihoo87/waveforms/issues).

{waveforms-3.5.1 → waveforms-3.7.0}/README.md

@@ -158,21 +158,51 @@ uses the same final limits. The filter state continues from the unclipped
 filtered signal across chunks. DAC `full_scale` controls integer conversion
 and saturation separately from these amplitude limits.
 
-Real-coefficient SOS filters (`filters=(sos, initial)`) run in the C core for
-float64 and complex128 signals. This stage subtracts the baseline `initial`,
-applies the cascade, restores the baseline, and applies the final limits.
+`filters` is a `defaultdict(float)` mapping exponential cascade time constants
+`tau` (in seconds) to amplitudes `amp`, independent of the sampling clock:
+
+```python
+stack.filters[100e-9] += 0.12
+stack.filters[2e-6] += -0.04
+samples = stack.sample(sample_rate=2_400_000_000)
+unfiltered = stack.sample(filters={})  # bypass predistortion for this call
+```
+
+The parameters describe cascade stages, not a parallel sum of exponential
+terms. Sampling uses `exp_decay_filter_from_cascade` followed by
+`exp_decay_filter(..., inv=True, output="sos")` at the actual sample rate:
+filtering defaults to **predistortion**. Coefficients are cached by parameter
+values and sample rate; changing an amplitude or the clock takes effect on the
+next sampling call. Only the parameters are saved by pickle, not cached SOS
+coefficients. Assign a mapping to replace them, or `None` to clear them. The old
+`(sos, initial)` representation is no longer accepted.
+
+The initial level is the first sample **after nonlinear mapping**, before
+output limiting: the system is assumed to have held that level indefinitely
+before playback. This stage subtracts that baseline, applies the inverse
+filter, restores the baseline, and applies the final limits. Chunked sampling
+retains both the initial level and the unclipped filter state across chunks;
+complex signals use the first I and Q values independently.
+
+SOS filtering runs in the C core for float64 and complex128 signals.
 Real int16/int32 output is quantized in the same stage, without allocating a
 full filtered floating-point buffer. Float output can reuse the sampled
 buffer. A small fixed scratch buffer keeps filtering and conversion local;
-waveform evaluation and nonlinear mapping still precede this stage. Complex
-coefficients and extended precision retain the SciPy implementation.
+waveform evaluation and nonlinear mapping still precede this stage.
 `sample_iq()` still converts the filtered complex result into separate I/Q
 output arrays. See [the SOS benchmark](benchmarks/sos_filter.md).
 
-Calling `waveform(t)` directly evaluates with amplitude limits but without
-nonlinear calibration or filtering. Sampling evaluates the underlying signal
-without limits before applying its processing chain. Limits are sampling
-metadata preserved by pickle, not part of the raw WNF4/WNS4 binary blocks.
+Calling `waveform(t)` applies waveform/event accumulation, the object's
+nonlinear mapping, and then its own amplitude limits. It does not apply SOS
+filters or DAC quantization. Stacks and complex wrappers use raw child values;
+child maps and limits do not affect the parent's processing chain. Thus direct
+evaluation and unfiltered floating-point sampling have the same processing
+semantics on the same time grid, subject to floating-point rounding. With
+`out=` and `accumulate=True`, the processed contribution is added to the
+existing buffer without mapping or limiting its previous contents. Sampling
+starts from raw values so mapping and limits are each applied only once, with
+SOS filtering between them when configured. Maps and limits are metadata
+preserved by pickle, not part of the raw WNF4/WNS4 binary blocks.
 
 ## Reporting Issues
 Please report all issues [on github](https://github.com/feihoo87/waveforms/issues).

waveforms-3.7.0/tests/test_common_pipeline.py

@@ -0,0 +1,242 @@
+"""Regression coverage for direct native loading and output placement."""
+
+import ctypes
+from concurrent.futures import ThreadPoolExecutor
+import importlib
+import pickle
+import struct
+
+import numpy as np
+import pytest
+
+import waveforms as wf
+import waveforms._waveform as core
+from waveforms._waveform import quantize_samples
+
+
+@pytest.fixture(scope='module')
+def native():
+    library = ctypes.CDLL(core.__file__)
+    library.cwaveform_stack_from_bytes.argtypes = [ctypes.c_void_p, ctypes.c_size_t]
+    library.cwaveform_stack_from_bytes.restype = ctypes.c_void_p
+    library.cwaveform_stack_release.argtypes = [ctypes.c_void_p]
+    library.cwaveform_stack_release.restype = None
+    library.cwaveform_stack_bytes.argtypes = [ctypes.c_void_p,
+                                            ctypes.POINTER(ctypes.c_size_t)]
+    library.cwaveform_stack_bytes.restype = ctypes.c_void_p
+    library.cwaveform_stack_hash.argtypes = [ctypes.c_void_p]
+    library.cwaveform_stack_hash.restype = ctypes.c_uint64
+    return library
+
+
+def _stack(delays, *, scales=None):
+    delays = np.asarray(delays, dtype=np.int64)
+    if scales is None:
+        scales = np.resize([.5, -.75, 1.0], len(delays))
+    stack = wf.WaveVStack.from_events(
+        [.8 * wf.square(8 / 120e9), -.3 * wf.square(4 / 120e9)],
+        np.arange(len(delays), dtype=np.uint32) % 2, delays, scales)
+    stack.start, stack.stop, stack.sample_rate = 0, 120 / 120e9, 120_000_000_000
+    stack.offset = .07
+    return stack
+
+
+def test_native_decode_owns_exact_bytes_and_preserves_hash(native):
+    original = _stack([-9, 0, 19, 33, 61, 118, 130])
+    data = original._core.to_bytes()
+    source = ctypes.create_string_buffer(data)
+    handle = native.cwaveform_stack_from_bytes(source, len(data))
+    assert handle
+    try:
+        # Mutating the transport buffer must not change the native handle.
+        ctypes.memset(source, 0, len(data))
+        size = ctypes.c_size_t()
+        pointer = native.cwaveform_stack_bytes(handle, ctypes.byref(size))
+        assert size.value == len(data)
+        assert ctypes.string_at(pointer, size.value) == data
+        assert native.cwaveform_stack_hash(handle) == original._core.hash64
+    finally:
+        native.cwaveform_stack_release(handle)
+
+
+def test_lazy_native_hash_matches_format_and_is_safe_for_parallel_readers(native):
+    stack = _stack(np.arange(10000) * 13)
+    data = stack._core.to_bytes()
+    expected = 1469598103934665603
+    for byte in data:
+        expected = ((expected ^ byte) * 1099511628211) & ((1 << 64) - 1)
+    source = ctypes.create_string_buffer(data)
+    handle = native.cwaveform_stack_from_bytes(source, len(data))
+    assert handle
+    try:
+        with ThreadPoolExecutor(max_workers=8) as workers:
+            hashes = list(workers.map(
+                lambda _: native.cwaveform_stack_hash(handle), range(64)))
+        assert hashes == [expected] * len(hashes)
+        assert stack._core.hash64 == expected
+    finally:
+        native.cwaveform_stack_release(handle)
+
+
+def test_native_decode_rejects_invalid_blocks_and_releases_partial_loads(native):
+    data = _stack([0, 16, 32])._core.to_bytes()
+    malformed = [data[:index] for index in range(len(data))]
+    event_offset = len(data) - 3 * 20
+    for offset, fmt, value in (
+        (0, '4s', b'BAD!'), (4, 'H', 65535), (6, 'H', 1),
+        (8, 'I', 2**32 - 1), (12, 'I', 2**32 - 1),
+        (16, 'I', 2**32 - 1),
+        (24 + 24, 'B', 255),  # First template's first node.
+        (event_offset, 'I', 2),
+        (event_offset + 12 * 3, 'd', np.nan),
+        (event_offset + 12 * 3 + 8, 'd', np.inf),
+        (event_offset + 12 * 3 + 16, 'd', -np.inf),
+    ):
+        candidate = bytearray(data)
+        struct.pack_into('<' + fmt, candidate, offset, value)
+        malformed.append(bytes(candidate))
+    for candidate in malformed:
+        source = ctypes.create_string_buffer(candidate)
+        handle = native.cwaveform_stack_from_bytes(source, len(candidate))
+        try:
+            assert not handle
+        finally:
+            if handle:
+                native.cwaveform_stack_release(handle)
+
+
+@pytest.mark.parametrize('delays', [[], [-30, -20], [140, 150], [0, 119],
+                                    [4, 10, 16, 22], [8, 30, 70],
+                                    [8, 30, 31], [80, 30, 8]])
+@pytest.mark.parametrize('bits', [0, 16, 32])
+@pytest.mark.parametrize('bounds', [(-np.inf, np.inf), (.1, .2)])
+def test_gap_initialization_edges_overlap_and_out_of_order(delays, bits, bounds):
+    stack = _stack(delays)
+    stack.min, stack.max = bounds
+    restored = pickle.loads(pickle.dumps(stack)) >> (1 / 120e9)
+    expected = restored._core.sample(0, 120, 1, 1, 1, stack.offset)
+    np.clip(expected, *bounds, out=expected)
+    if bits:
+        expected = quantize_samples(expected, bits, .7)
+    output = np.full_like(expected, 17)
+    assert restored.sample(out=output, full_scale=.7) is output
+    if bits:
+        np.testing.assert_array_equal(output, expected)
+    else:
+        # The plan groups by template; overlapping additions can differ from
+        # the event-order evaluator by a rounding bit even before this change.
+        np.testing.assert_allclose(output, expected, rtol=1e-15, atol=1e-15)
+    first = output.copy()
+    output.fill(23)
+    restored.sample(out=output, full_scale=.7)
+    np.testing.assert_array_equal(output, first)
+    reference = stack >> (1 / 120e9)
+    assert restored.begin == reference.begin
+    assert restored.end == reference.end
+    assert restored._core.lower_tick == stack._core.lower_tick
+    assert restored._core.upper_tick == stack._core.upper_tick
+
+
+def test_gap_initialization_skips_zero_scales_and_empty_templates():
+    stack = _stack([8, 30, 70], scales=[0, 1, 0])
+    expected = stack._core.sample(0, 120, 1, 1, 0, stack.offset)
+    np.testing.assert_array_equal(stack.sample(), expected)
+    empty = wf.WaveVStack.from_events([wf.zero()], [0], [0], [1.0])
+    empty.start, empty.stop, empty.sample_rate = 0, 1e-9, 10_000_000_000
+    np.testing.assert_array_equal(empty.sample(), np.zeros(10))
+
+
+@pytest.mark.parametrize('bits', [0, 16, 32])
+def test_many_scales_and_sparse_output(bits):
+    stack = _stack(np.arange(200) * 13, scales=np.linspace(-.8, .8, 200))
+    stack.stop = 2700 / 120e9
+    stack.min, stack.max = -.2, .25
+    expected = stack._core.sample(0, 2700, 1, 1, 0, stack.offset)
+    np.clip(expected, -.2, .25, out=expected)
+    if bits:
+        expected = quantize_samples(expected, bits, .7)
+    output = np.full_like(expected, 17)
+    stack.sample(out=output, full_scale=.7)
+    np.testing.assert_array_equal(output, expected)
+
+
+@pytest.mark.parametrize('templates_count', [1, 8, 9, 16, 33, 129])
+def test_plan_lookup_growth_repeated_keys_and_multiple_tick_phases(templates_count):
+    rng = np.random.default_rng(417)
+    templates = [wf.square((100 + index) / 120e9)
+                 for index in range(templates_count)]
+    count = 2 * templates_count + 100
+    ids = np.arange(count, dtype=np.uint32) % templates_count
+    delays = np.arange(count, dtype=np.int64) * 500 + rng.integers(0, 50, count)
+    scales = np.resize([.125, -.25, .5], count)
+    stack = wf.WaveVStack.from_events(templates, ids, delays, scales)
+    stack.start, stack.stop, stack.sample_rate = 0, count * 500 / 120e9, 2_400_000_000
+    restored = pickle.loads(pickle.dumps(stack)) >> (7 / 120e9)
+    samples = count * 10
+    expected = restored._core.sample(0, samples, 50, 1, 7, 0)
+    np.testing.assert_array_equal(restored.sample(), expected)
+    plan = restored._sample_plan_cache[1]
+    assert plan.group_count == len(set(zip(ids, (-(delays + 7)) % 50)))
+    np.testing.assert_array_equal(restored.sample(), expected)
+    # Rebuilding with a different calibration changes phases, not the format.
+    restored.shift = 11 / 120e9
+    expected = restored._core.sample(0, samples, 50, 1, 11, 0)
+    np.testing.assert_array_equal(restored.sample(), expected)
+
+
+@pytest.mark.parametrize('stack', [False, True])
+@pytest.mark.parametrize('rate', [2_400_000_000, 1_234_567_891])
+def test_float_output_is_written_directly(stack, rate, monkeypatch):
+    module = importlib.import_module('waveforms.waveform')
+    wave = wf.cos(2 * np.pi * 30e6)
+    if stack:
+        wave = wf.WaveVStack([wave * wf.square(2e-6)])
+    wave.start, wave.stop, wave.sample_rate = 0, 1e-6, rate
+    expected = wave.sample()
+    output = np.empty_like(expected)
+    finish = module._finish_samples
+
+    def check_direct(values, dtype, full_scale, out, *args):
+        assert values is output and out is output
+        return finish(values, dtype, full_scale, out, *args)
+
+    monkeypatch.setattr(module, '_finish_samples', check_direct)
+    assert wave.sample(out=output) is output
+    np.testing.assert_array_equal(output, expected)
+
+
+@pytest.mark.parametrize('stack', [False, True])
+@pytest.mark.parametrize('dtype', [None, np.float32, np.float64, np.complex128])
+@pytest.mark.parametrize('layout', ['contiguous', 'strided', 'unaligned', 'big_endian'])
+def test_output_casting_and_layout_fallbacks(stack, dtype, layout):
+    wave = .8 * wf.cos(2 * np.pi * 30e6)
+    if stack:
+        wave = wf.WaveVStack([wave * wf.square(2e-6)])
+    wave.start, wave.stop, wave.sample_rate = 0, 1e-6, 2_400_000_000
+    expected = wave.sample(dtype=dtype)
+    output_dtype = np.complex128 if dtype == np.complex128 else np.float64
+    if layout == 'strided':
+        output = np.empty(2 * len(expected), dtype=output_dtype)[::2]
+    elif layout == 'unaligned':
+        output = np.ndarray(expected.shape, dtype=output_dtype,
+                            buffer=bytearray(expected.size * np.dtype(output_dtype).itemsize + 1),
+                            offset=1)
+    else:
+        if layout == 'big_endian':
+            output_dtype = np.dtype(output_dtype).newbyteorder('>')
+        output = np.empty(expected.shape, dtype=output_dtype)
+    assert wave.sample(dtype=dtype, out=output) is output
+    np.testing.assert_array_equal(output, expected)
+
+
+@pytest.mark.parametrize('stack', [False, True])
+def test_float_output_validation(stack):
+    wave = _stack([10, 30]) if stack else wf.cos(1)
+    wave.start, wave.stop, wave.sample_rate = 0, 1e-6, 1_000_000_000
+    for output in (np.empty(999), np.empty((1, 1000))):
+        with pytest.raises(ValueError, match='shape'):
+            wave.sample(out=output)
+    output = np.empty(1000)
+    output.flags.writeable = False
+    with pytest.raises(ValueError, match='writ'):
+        wave.sample(out=output)

waveforms-3.7.0/tests/test_filter_parameters.py

@@ -0,0 +1,225 @@
+"""Clock-independent predistortion parameters and first-sample prehistory."""
+
+from collections import defaultdict
+import copy
+import pickle
+
+import numpy as np
+import pytest
+from scipy.signal import sosfilt
+
+import waveforms as wf
+import waveforms.waveform as impl
+from waveforms._waveform import quantize_samples
+
+
+KINDS = ("real", "stack", "complex", "complex_stack")
+STAGES = {50e-9: .12, 200e-9: -.04, 1e-6: .08}
+
+
+def _wave(kind, constant=False):
+    real = wf.const(.375) if constant else .125 + .25 * wf.cos(2 * np.pi * 7e6)
+    imag = wf.const(-.125) if constant else -.125 + .125 * wf.sin(2 * np.pi * 11e6)
+    if "stack" in kind:
+        real = wf.WaveVStack([.5 * real, .5 * real])
+        imag = wf.WaveVStack([.25 * imag, .75 * imag])
+    if kind == "complex":
+        real = wf.ComplexWaveform(real, imag)
+    elif kind == "complex_stack":
+        real = wf.ComplexWaveVStack(real, imag)
+    real.start, real.stop, real.sample_rate = 0., 256e-9, 1_000_000_000
+    return real
+
+
+def _reference(raw, stages, rate):
+    amp, tau = wf.exp_decay_filter_from_cascade(
+        [(amp, tau) for tau, amp in sorted(stages.items()) if amp != 0])
+    sos = wf.exp_decay_filter(amp, tau, rate, inv=True, output="sos")
+    return sosfilt(sos, raw - raw[0]) + raw[0]
+
+
+@pytest.mark.parametrize("kind", KINDS)
+def test_default_mapping_assignment_and_independent_copies(kind):
+    wave = _wave(kind)
+    other = _wave(kind)
+    assert isinstance(wave.filters, defaultdict)
+    assert wave.filters.default_factory is float
+    assert wave.filters[50e-9] == 0
+    wave.filters[50e-9] += .12
+    assert other.filters == {}
+    params = defaultdict(lambda: 99, STAGES)
+    wave.filters = params
+    params[50e-9] = .9
+    assert wave.filters == STAGES
+    assert wave.filters.default_factory is float
+    for duplicate in (copy.copy(wave), copy.deepcopy(wave),
+                      pickle.loads(pickle.dumps(wave))):
+        assert isinstance(duplicate.filters, defaultdict)
+        assert duplicate.filters == STAGES
+        assert duplicate.filters is not wave.filters
+        duplicate.filters[50e-9] += .05
+        assert wave.filters == STAGES
+    wave.filters = None
+    assert isinstance(wave.filters, defaultdict)
+    assert wave.filters == {}
+
+
+@pytest.mark.parametrize("kind", ["stack", "complex_stack"])
+def test_delay_calibration_preserves_but_does_not_alias_filters(kind):
+    wave = _wave(kind)
+    wave.filters = STAGES
+    restored = pickle.loads(pickle.dumps(wave))
+    shifted = restored >> 2e-9
+    assert shifted.filters == STAGES
+    raw = shifted.sample(filters={})
+    np.testing.assert_allclose(shifted.sample(),
+                               _reference(raw, STAGES, shifted.sample_rate),
+                               rtol=3e-12, atol=3e-13)
+    shifted.filters[50e-9] += .01
+    assert restored.filters == STAGES
+
+
+@pytest.mark.parametrize("kind", KINDS)
+@pytest.mark.parametrize("rate", [500_000_000, 1_200_000_000, 2_400_000_000,
+                                   7_000_000_000, 1_234_567_890.5])
+def test_rate_override_inverse_filter_and_chunked_first_sample(kind, rate):
+    wave = _wave(kind)
+    wave.filters = STAGES
+    raw = wave.sample(rate, filters={})
+    expected = _reference(raw, STAGES, rate)
+    actual = wave.sample(rate)
+    assert actual[0] == raw[0]
+    assert not np.allclose(actual, raw)
+    # Native real/imag recurrences and SciPy complex arithmetic round slightly
+    # differently for poles this close to one (small accumulated roundoff).
+    np.testing.assert_allclose(actual, expected, rtol=3e-12, atol=2e-12)
+    for chunk_size in (1, 31, 256, len(raw) + 1):
+        target = np.empty_like(expected)
+        chunks = list(wave.sample(rate, chunk_size=chunk_size, out=target))
+        np.testing.assert_allclose(np.concatenate(chunks), expected,
+                                   rtol=3e-12, atol=2e-12)
+        np.testing.assert_allclose(target, expected, rtol=3e-12, atol=2e-12)
+    # Changing the device clock must not modify the serialized calibration.
+    assert wave.sample_rate == 1_000_000_000
+    assert wave.filters == STAGES
+
+
+@pytest.mark.parametrize("kind", KINDS)
+def test_constant_prehistory_has_no_startup_transient_after_mapping(kind):
+    wave = _wave(kind, constant=True)
+    wave.filters = STAGES
+    mapping = wf.NonlinearMap.from_samples(
+        [-1., 1.], [-.5, 1.5], method="linear", table_size=2)
+    wave.nonlinear = (mapping, mapping) if "complex" in kind else mapping
+    expected = .875 + .375j if "complex" in kind else .875
+    np.testing.assert_array_equal(wave.sample(), np.full(256, expected))
+    chunks = np.concatenate(list(wave.sample(chunk_size=7)))
+    np.testing.assert_array_equal(chunks, np.full(256, expected))
+
+
+@pytest.mark.parametrize("kind", KINDS)
+@pytest.mark.parametrize("dtype", [np.int16, np.int32])
+def test_initial_level_precedes_clipping_and_quantization(kind, dtype):
+    wave = _wave(kind)
+    wave.filters = STAGES
+    mapping = wf.NonlinearMap.from_samples(
+        [-1., 1.], [-.75, 1.25], method="linear", table_size=2)
+    wave.nonlinear = (mapping, mapping) if "complex" in kind else mapping
+    raw = wave.sample(filters={})
+    filtered = _reference(raw, STAGES, wave.sample_rate)
+    wave.min, wave.max = -.1, .2
+    bits = np.dtype(dtype).itemsize * 8
+    if "complex" in kind:
+        expected = tuple(quantize_samples(np.clip(v, -.1, .2), bits)
+                         for v in (filtered.real, filtered.imag))
+        actual = wave.sample_iq(dtype=dtype)
+        for component, reference in zip(actual, expected):
+            np.testing.assert_array_equal(component, reference)
+        chunks = list(wave.sample_iq(dtype=dtype, chunk_size=1))
+        for index in (0, 1):
+            np.testing.assert_array_equal(
+                np.concatenate([chunk[index] for chunk in chunks]), expected[index])
+    else:
+        expected = quantize_samples(np.clip(filtered, -.1, .2), bits)
+        np.testing.assert_array_equal(wave.sample(dtype=dtype), expected)
+        np.testing.assert_array_equal(
+            np.concatenate(list(wave.sample(dtype=dtype, chunk_size=1))), expected)
+
+
+@pytest.mark.parametrize("kind", KINDS)
+def test_empty_and_single_sample(kind):
+    wave = _wave(kind)
+    wave.filters = STAGES
+    wave.stop = wave.start
+    assert wave.sample().size == 0
+    assert list(wave.sample(chunk_size=1)) == []
+    wave.stop = 1e-9
+    expected = wave.sample(filters={})
+    assert len(expected) == 1
+    np.testing.assert_array_equal(wave.sample(), expected)
+    np.testing.assert_array_equal(np.concatenate(list(wave.sample(chunk_size=1))), expected)
+
+
+def test_cache_tracks_values_and_rate_but_not_initial_or_filter_state():
+    impl._exp_decay_sos.cache_clear()
+    wave = _wave("real")
+    wave.filters = STAGES
+    before = pickle.dumps(wave)
+    initial_result = wave.sample()
+    assert impl._exp_decay_sos.cache_info().misses == 1
+    assert pickle.dumps(wave) == before
+    np.testing.assert_array_equal(wave.sample(), initial_result)
+    wave.filters = dict(reversed(list(STAGES.items())))
+    wave.filters[2e-6]  # Reading a missing tau must not invalidate the cache.
+    np.testing.assert_array_equal(wave.sample(), initial_result)
+    assert impl._exp_decay_sos.cache_info().misses == 1
+    # A different signal shares coefficients, not its first point or state.
+    other = _wave("complex")
+    other.filters = STAGES
+    other.sample()
+    assert impl._exp_decay_sos.cache_info().misses == 1
+    wave.filters[50e-9] += .1
+    assert not np.allclose(wave.sample(), initial_result)
+    assert impl._exp_decay_sos.cache_info().misses == 2
+    wave.sample(2_400_000_000)
+    assert impl._exp_decay_sos.cache_info().misses == 3
+
+
+def test_explicit_mapping_override_and_snapshot_during_stream():
+    wave = _wave("real")
+    wave.filters = STAGES
+    raw = wave.sample(filters={})
+    override = {75e-9: .2}
+    expected = _reference(raw, override, wave.sample_rate)
+    stream = wave.sample(filters=override, chunk_size=31)
+    chunks = [next(stream)]
+    override[75e-9] = .4
+    wave.filters[50e-9] = .5
+    chunks.extend(stream)
+    np.testing.assert_allclose(np.concatenate(chunks), expected,
+                               rtol=3e-12, atol=3e-13)
+    np.testing.assert_array_equal(wave.sample(filters={75e-9: 0}), raw)
+    np.testing.assert_array_equal(wave.sample(filters={}), raw)
+
+
+@pytest.mark.parametrize("params,message", [
+    ({0.: .1}, "positive"), ({-1.: .1}, "positive"),
+    ({np.inf: .1}, "finite"), ({np.nan: .1}, "finite"),
+    ({1e-6: np.nan}, "finite"), ({1e-6: np.inf}, "finite"),
+])
+def test_invalid_active_parameters(params, message):
+    wave = _wave("real")
+    wave.filters = params
+    with pytest.raises(ValueError, match=message):
+        wave.sample()
+    with pytest.raises(ValueError, match=message):
+        list(wave.sample(chunk_size=7))
+
+
+def test_old_sos_tuple_is_not_a_parameter_mapping():
+    wave = _wave("real")
+    old = (np.array([[1., 0., 0., 1., 0., 0.]]), 0.)
+    with pytest.raises(TypeError, match="mapping"):
+        wave.filters = old
+    with pytest.raises(TypeError, match="mapping"):
+        wave.sample(filters=old)

{waveforms-3.5.1 → waveforms-3.7.0}/tests/test_native_sos.py

@@ -6,6 +6,7 @@ from scipy.signal import butter, sosfilt
 
 import waveforms as wf
 from waveforms._waveform import quantize_samples, sosfilt_samples
+from waveforms.waveform import _filter_and_finish
 
 
 def _clip(values, lower, upper):
@@ -148,17 +149,24 @@ def test_scipy_fallback(coefficient_dtype):
     sos = butter(4, .3, output="sos").astype(coefficient_dtype)
     if coefficient_dtype == np.complex128:
         sos[0, 0] += .1j
-    wave.filters = sos, .03
     raw = .4 + .5 * np.cos(6 * np.pi * np.arange(1024) / 1024)
     expected = _clip(sosfilt(sos, raw - .03) + .03, wave.min, wave.max)
-    np.testing.assert_allclose(wave.sample(), expected, rtol=3e-13, atol=3e-14)
-    np.testing.assert_allclose(np.concatenate(list(wave.sample(chunk_size=73))),
-                               expected, rtol=3e-13, atol=3e-14)
+    result, _ = _filter_and_finish(
+        raw.copy(), sos, None, 1., None, wave.min, wave.max, initial=.03)
+    np.testing.assert_allclose(result, expected, rtol=3e-13, atol=3e-14)
+    chunks, state = [], None
+    for start in range(0, len(raw), 73):
+        result, state = _filter_and_finish(
+            raw[start:start + 73].copy(), sos, None, 1., None,
+            wave.min, wave.max, state, initial=.03)
+        chunks.append(result)
+    np.testing.assert_allclose(np.concatenate(chunks), expected,
+                               rtol=3e-13, atol=3e-14)
 
 
-def test_pipeline_output_casting_and_single_section_vector():
+def test_pipeline_output_casting_and_single_section():
     wave = _wave()
-    wave.filters = butter(2, .3, output="sos")[0], .03
+    wave.filters = {.04: .2}
     expected = wave.sample()
     for dtype in (None, np.float32, np.float64):
         for stride in (1, 2):

{waveforms-3.5.1 → waveforms-3.7.0}/tests/test_nonlinear.py

@@ -3,7 +3,7 @@ import pickle
 import numpy as np
 import pytest
 from scipy.interpolate import PchipInterpolator
-from scipy.signal import butter, sosfilt, tf2sos
+from scipy.signal import sosfilt
 
 import waveforms as wf
 from waveforms._waveform import quantize_samples
@@ -129,14 +129,13 @@ def test_waveform_sampling_order_chunking_quantization_and_pickle():
         [0.0, 0.0625, 0.25, 0.5625, 1.0],
         table_size=257,
     )
-    b, a = butter(3, 40.0, "lowpass", fs=sample_rate)
-    sos = tf2sos(b, a)
+    sos = wf.exp_decay_filter(.2, .04, sample_rate, inv=True, output="sos")
     waveform = wf.t()
     waveform.start = 0.0
     waveform.stop = 1.0
     waveform.sample_rate = sample_rate
     waveform.nonlinear = mapping
-    waveform.filters = (sos, 0.0)
+    waveform.filters = {.04: .2}
 
     raw = np.arange(sample_rate, dtype=np.float64) / sample_rate
     expected = sosfilt(sos, mapping(raw))