waveforms 3.6.1__tar.gz → 3.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: waveforms
-Version: 3.6.1
+Version: 3.7.0
 Summary: Edit waveforms used in experiment
 Author-email: feihoo87 <feihoo87@gmail.com>
 Maintainer-email: feihoo87 <feihoo87@gmail.com>
@@ -202,14 +202,37 @@ 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).
 

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

@@ -158,14 +158,37 @@ 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).
 

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.6.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.6.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))

{waveforms-3.6.1 → waveforms-3.7.0}/tests/test_output_limits.py

@@ -49,14 +49,13 @@ def _clip(values, lower, upper):
 
 @pytest.mark.parametrize("kind", ["real", "stack", "complex", "complex_stack"])
 @pytest.mark.parametrize("rate", [128, 127.5])
-@pytest.mark.parametrize("gain", [0.25, 2.0])
-def test_output_limits_follow_mapping_and_filter_with_chunk_state(kind, rate, gain):
+@pytest.mark.parametrize("amp", [0.25, -0.5])
+def test_output_limits_follow_mapping_and_filter_with_chunk_state(kind, rate, amp):
     wave = _configure(_signal(kind), rate)
     wave.min, wave.max = -0.22, 0.27
     # Stateful filter exercises overshoot and continuing with the unclipped zf.
-    sos = np.array([[gain * 0.5, 0., 0., 1., -0.5, 0.]])
-    initial = 0.03
-    wave.filters = (sos, initial)
+    sos = wf.exp_decay_filter(amp, .04, rate, inv=True, output="sos")
+    wave.filters = {.04: amp}
     mapping = wf.NonlinearMap.from_samples(
         [-3., 3.], [-6., 6.], method="linear", table_size=2)
     wave.nonlinear = (mapping, mapping) if "complex" in kind else mapping
@@ -65,6 +64,7 @@ def test_output_limits_follow_mapping_and_filter_with_chunk_state(kind, rate, ga
     raw = 0.45 + 0.35 * np.cos(6 * np.pi * positions)
     if "complex" in kind:
         raw = raw + 1j * (-0.3 + 0.2 * np.sin(4 * np.pi * positions))
+    initial = 2 * raw[0]
     filtered = sosfilt(sos, 2 * raw - initial) + initial
     expected = _clip(filtered, wave.min, wave.max)
 
@@ -103,11 +103,17 @@ def test_output_limits_follow_mapping_and_filter_with_chunk_state(kind, rate, ga
             np.testing.assert_array_equal(np.concatenate(list(chunks)), expected_integer)
 
 
-@pytest.mark.parametrize("gain,expected", [(2., .2), (.25, .1)])
-def test_filter_gain_never_sees_prematurely_limited_input(gain, expected):
-    wave = _configure(wf.const(.4))
+@pytest.mark.parametrize("amp", [.5, -.5])
+def test_filter_never_sees_prematurely_limited_input(amp):
+    wave = _configure(.4 - .35 * (wf.step(0) >> .25))
     wave.min, wave.max = -.2, .2
-    wave.filters = (np.array([[gain, 0., 0., 1., 0., 0.]]), 0.)
+    wave.filters = {.03: amp}
+    sos = wf.exp_decay_filter(amp, .03, wave.sample_rate, inv=True, output="sos")
+    raw = np.where(np.arange(128) < 32, .4, .05)
+    expected = np.clip(sosfilt(sos, raw - raw[0]) + raw[0], -.2, .2)
+    limited = np.clip(raw, -.2, .2)
+    premature = np.clip(sosfilt(sos, limited - limited[0]) + limited[0], -.2, .2)
+    assert not np.allclose(expected, premature)
     np.testing.assert_allclose(wave.sample(), expected)
     np.testing.assert_allclose(np.concatenate(list(wave.sample(chunk_size=7))), expected)
 

{waveforms-3.6.1 → waveforms-3.7.0}/tests/test_waveform.py

@@ -6,7 +6,7 @@ from pathlib import Path
 import numpy as np
 import pytest
 import scipy.special as special
-from scipy.signal import butter, lfilter, lfiltic, tf2sos
+from scipy.signal import sosfilt
 
 import waveforms as wf
 from waveforms._waveform import (
@@ -252,16 +252,15 @@ def test_multi_frequency_drag_matches_120ghz_tick_behavior():
 
 def test_filters_and_chunked_sampling():
     sample_rate = 1000
-    b, a = butter(3, 4.0, "lowpass", fs=sample_rate)
-    zi = lfiltic(b, a, [0])
+    sos = wf.exp_decay_filter(.2, .04, sample_rate, inv=True, output="sos")
     x = np.linspace(-1, 1, 2000, endpoint=False)
 
     wav = wf.step(0)
     wav.start = -1
     wav.stop = 1
     wav.sample_rate = sample_rate
-    wav.filters = (tf2sos(b, a), 0)
-    expected = lfilter(b, a, np.heaviside(x, 1), zi=zi)[0]
+    wav.filters = {.04: .2}
+    expected = sosfilt(sos, np.heaviside(x, 1))
     assert np.allclose(wav.sample(), expected)
     assert np.allclose(np.concatenate(list(wav.sample(chunk_size=137))), expected)
 
@@ -575,8 +574,7 @@ def test_integer_sampling_filtered_and_overlapping_fallbacks_are_exact():
         quantize_samples(overlapping.sample(rate), 16),
     )
 
-    b, a = butter(3, 50e6, "lowpass", fs=rate)
-    overlapping.filters = (tf2sos(b, a), 0)
+    overlapping.filters = {20e-9: .2}
     assert np.array_equal(
         overlapping.sample(rate, dtype=np.int16),
         quantize_samples(overlapping.sample(rate), 16),

{waveforms-3.6.1 → waveforms-3.7.0}/tests/test_wavevstack.py

@@ -1,10 +1,10 @@
 import pickle
 
 import numpy as np
-from scipy.signal import butter, lfilter, lfiltic, tf2sos
+from scipy.signal import sosfilt
 
 from waveforms import (
-    Waveform, WaveVStack, cos, gaussian, pi, poly, sin, step,
+    Waveform, WaveVStack, cos, exp_decay_filter, gaussian, pi, poly, sin, step,
     time_to_tick, zero,
 )
 
@@ -35,18 +35,15 @@ def test_wavevstack_sampling_algebra_and_shifts():
 
 def test_wavevstack_filtering_and_chunked_sampling():
     sample_rate = 1000
-    b, a = butter(3, 4.0, "lowpass", fs=sample_rate)
-    zi = lfiltic(b, a, [0])
+    sos = exp_decay_filter(.2, .04, sample_rate, inv=True, output="sos")
     x = np.linspace(-1, 1, 2000, endpoint=False)
 
     stack = WaveVStack([step(0) << 0.5, -step(0)])
     stack.sample_rate = sample_rate
     stack.start = -1
     stack.stop = 1
-    stack.filters = (tf2sos(b, a), 0)
-    expected = lfilter(
-        b, a, np.heaviside(x + 0.5, 1) - np.heaviside(x, 1), zi=zi
-    )[0]
+    stack.filters = {.04: .2}
+    expected = sosfilt(sos, np.heaviside(x + 0.5, 1) - np.heaviside(x, 1))
 
     assert np.allclose(stack.sample(), expected, atol=1e-6)
     chunks = np.concatenate(list(stack.sample(chunk_size=137)))

{waveforms-3.6.1 → waveforms-3.7.0}/waveforms/version.py

@@ -1,2 +1,2 @@
 """Define version number here and read it from setup.py automatically"""
-__version__ = "3.6.1"
+__version__ = "3.7.0"

{waveforms-3.6.1 → waveforms-3.7.0}/waveforms/waveform.py

@@ -9,6 +9,8 @@ from __future__ import annotations
 
 import io
 import struct
+from collections import defaultdict
+from collections.abc import Mapping
 from functools import lru_cache
 from typing import Iterable, cast
 
@@ -16,6 +18,7 @@ import numpy as np
 from numpy import e, inf, pi
 from scipy.signal import sosfilt
 
+from .distortion import exp_decay_filter, exp_decay_filter_from_cascade
 from .nonlinear import NonlinearMap
 
 from ._waveform import (
@@ -102,7 +105,7 @@ def _copy_sampling_metadata(source, target):
     target.start = source.start
     target.stop = source.stop
     target.sample_rate = source.sample_rate
-    target.filters = source.filters
+    target.filters = source._filters
     target.nonlinear = source.nonlinear
     target.label = source.label
     return target
@@ -332,10 +335,38 @@ def _real_sampling_output(dtype, bits, out):
     return None
 
 
-def _filter_samples(sig, filters, zi=None):
+@lru_cache(maxsize=128)
+def _exp_decay_sos(stages, sample_rate):
+    """Compile a snapshot of cascade parameters for one sampling clock."""
+    if not np.isfinite(sample_rate) or sample_rate <= 0:
+        raise ValueError("sample_rate must be a finite positive number")
+    amp, tau = exp_decay_filter_from_cascade(
+        [(amp, tau) for tau, amp in stages])
+    sos = np.ascontiguousarray(
+        exp_decay_filter(amp, tau, sample_rate, inv=True, output='sos'),
+        dtype=np.float64)
+    if not np.all(np.isfinite(sos)):
+        raise ValueError("filters produce non-finite SOS coefficients")
+    # Cache coefficients, never mutable streaming state or a signal's baseline.
+    sos.flags.writeable = False
+    return sos
+
+
+def _prepare_filters(filters, sample_rate):
     if filters is None:
-        return sig, zi
-    sos, initial = filters
+        return None
+    if not isinstance(filters, Mapping):
+        raise TypeError("filters must be a mapping from tau (seconds) to amp")
+    if not filters:
+        return None
+    # Ignore missing-key/default-zero entries and key the cache by values, so
+    # edits through filters[tau] += amp take effect on the next sampling call.
+    stages = tuple(sorted((float(tau), float(amp))
+                          for tau, amp in filters.items() if amp != 0))
+    return _exp_decay_sos(stages, float(sample_rate)) if stages else None
+
+
+def _filter_samples(sig, sos, initial, zi=None):
     sos = np.asarray(sos)
     if not sos.flags.writeable:
         sos = sos.copy()
@@ -349,20 +380,20 @@ def _filter_samples(sig, filters, zi=None):
     return filtered, zi
 
 
-def _filter_and_finish(sig, filters, dtype, full_scale, out,
-                       minimum, maximum, zi=None):
-    if filters is None:
+def _filter_and_finish(sig, sos, dtype, full_scale, out,
+                       minimum, maximum, zi=None, initial=None):
+    if sos is None:
         return _finish_samples(
             sig, dtype, full_scale, out, minimum, maximum), zi
-    sos, initial = filters
     sos = np.asarray(sos)
-    initial = initial if initial else 0.0
+    if initial is None:
+        initial = sig[0] if len(sig) else 0.0
     values_dtype = np.result_type(sig, np.asarray(initial), sos,
                                   zi if zi is not None else np.float64)
     # Preserve SciPy's complex-coefficient and extended-precision behavior.
     if (sos.dtype.kind not in 'biuf' or sos.dtype.itemsize > 8
             or values_dtype not in (np.dtype(np.float64), np.dtype(np.complex128))):
-        sig, zi = _filter_samples(sig, filters, zi)
+        sig, zi = _filter_samples(sig, sos, initial, zi)
         return _finish_samples(
             sig, dtype, full_scale, out, minimum, maximum), zi
     dtype, bits = _quantization_bits(dtype, out)
@@ -479,11 +510,32 @@ class Waveform(metaclass=_WaveformMeta):
     start: float | None
     stop: float | None
     sample_rate: float | None
-    filters: tuple[np.ndarray, float] | None
+    _filters: defaultdict[float, float] | None
     nonlinear: NonlinearMap | tuple[NonlinearMap | None, NonlinearMap | None] | None
     min: float
     max: float
 
+    @property
+    def filters(self) -> defaultdict[float, float]:
+        """Exponential cascade stages: time constant (seconds) -> amplitude.
+
+        Missing amplitudes default to zero. SOS coefficients are derived from
+        these parameters at sampling time using the actual sample rate and
+        ``inv=True`` (predistortion).
+        """
+        # Most temporary expression nodes never use filters. Allocate only on
+        # access, keeping pulse construction and unfiltered sampling cheap.
+        if self._filters is None:
+            self._filters = defaultdict(float)
+        return self._filters
+
+    @filters.setter
+    def filters(self, value: Mapping[float, float] | None):
+        if value is not None and not isinstance(value, Mapping):
+            raise TypeError("filters must be a mapping from tau (seconds) to amp")
+        # Copy on assignment: metadata on shifted/copied objects is independent.
+        self._filters = None if not value else defaultdict(float, value)
+
     def _evaluate_raw(self, x):
         """Evaluate before output limits, nonlinear calibration or filtering."""
         return self(x, _raw=True)
@@ -508,8 +560,15 @@ class Waveform(metaclass=_WaveformMeta):
 
     def sample(self, sample_rate=None, out: np.ndarray | None = None,
                chunk_size=None, function_lib=None,
-               filters: tuple[np.ndarray, float] | None = None,
+               filters: Mapping[float, float] | None = None,
                dtype=None, full_scale=1.0, nonlinear=None):
+        """Sample, map, filter, limit, then convert to the requested dtype.
+
+        ``filters=None`` uses this object's tau-to-amp cascade; ``filters={}``
+        disables it for this call. Filtering assumes the mapped first sample
+        was held indefinitely before playback. The baseline and filter state
+        persist across chunks of this sampling call.
+        """
         minimum, maximum = _amplitude_limits(self)
         if function_lib is not None:
             raise NotImplementedError("custom waveform functions are not supported")
@@ -520,14 +579,14 @@ class Waveform(metaclass=_WaveformMeta):
                 f"Waveform is not initialized. {self.start=}, {self.stop=}, "
                 f"{sample_rate=}"
             )
-        if filters is None:
-            filters = self.filters
+        sos = _prepare_filters(self._filters if filters is None else filters,
+                               sample_rate)
         if nonlinear is None:
             nonlinear = self.nonlinear
         dtype, bits = _quantization_bits(dtype, out)
         if chunk_size is not None:
             return self._sample_iter(
-                sample_rate, int(chunk_size), out, filters, dtype, full_scale,
+                sample_rate, int(chunk_size), out, sos, dtype, full_scale,
                 nonlinear,
             )
 
@@ -536,7 +595,7 @@ class Waveform(metaclass=_WaveformMeta):
             x = np.arange(self.start, self.stop, 1 / float(sample_rate))
             sig = cast(np.ndarray, self._evaluate_raw(x))
         else:
-            if bits is not None and filters is None and nonlinear is None:
+            if bits is not None and sos is None and nonlinear is None:
                 specialized = getattr(
                     self, "_sample_supported_quantized", None
                 )
@@ -549,7 +608,7 @@ class Waveform(metaclass=_WaveformMeta):
             sig = self._sample_supported(*plan)
         sig = _apply_nonlinear(sig, nonlinear)
         result, _ = _filter_and_finish(
-            sig, filters, dtype, full_scale, out, minimum, maximum)
+            sig, sos, dtype, full_scale, out, minimum, maximum)
         return cast(np.ndarray, result)
 
     def _sample_supported(self, start_tick, count, step_numerator,
@@ -558,13 +617,14 @@ class Waveform(metaclass=_WaveformMeta):
                         index_offset)
         return cast(np.ndarray, self._evaluate_raw(x))
 
-    def _sample_iter(self, sample_rate, chunk_size, out, filters, dtype,
+    def _sample_iter(self, sample_rate, chunk_size, out, sos, dtype,
                      full_scale, nonlinear):
         minimum, maximum = _amplitude_limits(self)
         start = cast(float, self.start)
         stop = cast(float, self.stop)
         output_index = 0
         zi = None
+        initial = None
         if chunk_size <= 0:
             raise ValueError("chunk_size must be positive")
         plan = _sampling_plan(start, stop, sample_rate)
@@ -596,8 +656,10 @@ class Waveform(metaclass=_WaveformMeta):
             target = (None if output is None
                       else output[output_index:output_index + size])
             sig = _apply_nonlinear(sig, nonlinear)
+            if initial is None and sos is not None:
+                initial = sig[0]
             sig, zi = _filter_and_finish(
-                sig, filters, dtype, full_scale, target, minimum, maximum, zi)
+                sig, sos, dtype, full_scale, target, minimum, maximum, zi, initial)
             yield sig
             output_index += size
 
@@ -638,7 +700,7 @@ class _RealWaveformBase(Waveform):
 
     __slots__ = (
         "_core", "max", "min", "start", "stop", "sample_rate",
-        "filters", "nonlinear", "label",
+        "_filters", "nonlinear", "label",
     )
 
 
@@ -647,7 +709,7 @@ class ComplexWaveform(Waveform):
 
     __slots__ = (
         "_real", "_imag", "max", "min", "start", "stop", "sample_rate",
-        "filters", "nonlinear", "label",
+        "_filters", "nonlinear", "label",
     )
 
     def __init__(self, real=0.0, imag=0.0):
@@ -681,7 +743,7 @@ class ComplexWaveform(Waveform):
         self.start = None
         self.stop = None
         self.sample_rate = None
-        self.filters = None
+        self._filters = None
         self.nonlinear = None
         self.label = None
 
@@ -913,7 +975,7 @@ class ComplexWaveform(Waveform):
 
     def __getstate__(self):
         return (self.to_bytes(), self.max, self.min, self.start, self.stop,
-                self.sample_rate, self.filters, self.nonlinear, self.label)
+                self.sample_rate, self._filters, self.nonlinear, self.label)
 
     def __setstate__(self, state):
         if len(state) == 8:
@@ -965,7 +1027,7 @@ class _RealWaveVStackBase(WaveVStack):
     """Common real-stack type; concrete storage is provided by the C core."""
 
     __slots__ = (
-        "start", "stop", "sample_rate", "offset", "filters", "nonlinear", "label",
+        "start", "stop", "sample_rate", "offset", "_filters", "nonlinear", "label",
         "function_lib", "_sample_plan_cache", "min", "max",
     )
 
@@ -975,7 +1037,7 @@ class ComplexWaveVStack(WaveVStack):
 
     __slots__ = (
         "_real_stack", "_imag_stack", "start", "stop", "sample_rate",
-        "offset", "shift", "filters", "nonlinear", "label", "function_lib",
+        "offset", "shift", "_filters", "nonlinear", "label", "function_lib",
         "min", "max",
     )
 
@@ -1021,7 +1083,7 @@ class ComplexWaveVStack(WaveVStack):
         self.start = None
         self.stop = None
         self.sample_rate = None
-        self.filters = None
+        self._filters = None
         self.nonlinear = None
         self.label = None
         self.function_lib = None
@@ -1177,7 +1239,7 @@ class ComplexWaveVStack(WaveVStack):
         else:
             real, imag = _number_parts(other)
             result = ComplexWaveVStack(self.real + real, self.imag + imag)
-        result.filters = self.filters
+        result.filters = self._filters
         result.label = self.label
         return result
 
@@ -1209,7 +1271,7 @@ class ComplexWaveVStack(WaveVStack):
                 self.real * real - self.imag * imag,
                 self.real * imag + self.imag * real,
             )
-        result.filters = self.filters
+        result.filters = self._filters
         result.label = self.label
         return result
 
@@ -1265,7 +1327,7 @@ class ComplexWaveVStack(WaveVStack):
 
     def __getstate__(self):
         return (self.to_bytes(), self.start, self.stop, self.sample_rate,
-                self.filters, self.nonlinear, self.label, self.min, self.max)
+                self._filters, self.nonlinear, self.label, self.min, self.max)
 
     def __setstate__(self, state):
         self.min, self.max = state[7:] if len(state) == 9 else (-inf, inf)
@@ -1333,7 +1395,7 @@ class RealWaveform(_RealWaveformBase):
         self.start = None
         self.stop = None
         self.sample_rate = None
-        self.filters = None
+        self._filters = None
         self.nonlinear = None
         self.label = None
 
@@ -1447,8 +1509,8 @@ class RealWaveform(_RealWaveformBase):
             sample_rate = self.sample_rate
         if self.start is None or self.stop is None or sample_rate is None:
             raise ValueError("RealWaveform sampling metadata is incomplete")
-        if filters is None:
-            filters = self.filters
+        sos = _prepare_filters(self._filters if filters is None else filters,
+                               sample_rate)
         if nonlinear is None:
             nonlinear = self.nonlinear
         plan = _sampling_plan(self.start, self.stop, sample_rate)
@@ -1459,7 +1521,7 @@ class RealWaveform(_RealWaveformBase):
             values = self._evaluate_raw(positions)
         else:
             start_tick, count, step_numerator, step_denominator = plan
-            if filters is None and nonlinear is None:
+            if sos is None and nonlinear is None:
                 values = self._core.sample(
                     start_tick, count, step_numerator, step_denominator,
                     self._delay_tick, self._scale, minimum, maximum,
@@ -1473,7 +1535,7 @@ class RealWaveform(_RealWaveformBase):
             )
         values = _apply_nonlinear(values, nonlinear)
         result, _ = _filter_and_finish(
-            values, filters, dtype, full_scale, out, minimum, maximum)
+            values, sos, dtype, full_scale, out, minimum, maximum)
         return result
 
     def to_bytes(self):
@@ -1624,7 +1686,7 @@ class RealWaveform(_RealWaveformBase):
 
     def __getstate__(self):
         return (self.to_bytes(), self.max, self.min, self.start, self.stop,
-                self.sample_rate, self.filters, self.nonlinear, self.label)
+                self.sample_rate, self._filters, self.nonlinear, self.label)
 
     def __setstate__(self, state):
         _ensure_c_clock_locked()
@@ -1716,7 +1778,7 @@ class RealWaveVStack(_RealWaveVStackBase):
         self.sample_rate = None
         self.offset = 0.0
         self._shift_tick = 0
-        self.filters = None
+        self._filters = None
         self.nonlinear = None
         self.label = None
         self.function_lib = None
@@ -1831,8 +1893,8 @@ class RealWaveVStack(_RealWaveVStackBase):
             sample_rate = self.sample_rate
         if self.start is None or self.stop is None or sample_rate is None:
             raise ValueError("RealWaveVStack sampling metadata is incomplete")
-        if filters is None:
-            filters = self.filters
+        sos = _prepare_filters(self._filters if filters is None else filters,
+                               sample_rate)
         if nonlinear is None:
             nonlinear = self.nonlinear
         plan = _sampling_plan(self.start, self.stop, sample_rate)
@@ -1856,7 +1918,7 @@ class RealWaveVStack(_RealWaveVStackBase):
                 )
                 self._sample_plan_cache = cache_key, sample_plan
             if sample_plan is not None:
-                if filters is None and nonlinear is None:
+                if sos is None and nonlinear is None:
                     values = sample_plan.sample(
                         self.offset, bits or 0, full_scale,
                         _real_sampling_output(dtype, bits, out), minimum, maximum,
@@ -1865,7 +1927,7 @@ class RealWaveVStack(_RealWaveVStackBase):
                             _finish_samples(values, dtype, full_scale, out))
                 values = sample_plan.sample(self.offset)
             else:
-                if filters is None and nonlinear is None:
+                if sos is None and nonlinear is None:
                     values = self._core.sample(
                         start_tick, count, step_numerator, step_denominator,
                         self._shift_tick, self.offset, bits or 0, full_scale,
@@ -1882,7 +1944,7 @@ class RealWaveVStack(_RealWaveVStackBase):
                 )
         values = _apply_nonlinear(values, nonlinear)
         result, _ = _filter_and_finish(
-            values, filters, dtype, full_scale, out, minimum, maximum)
+            values, sos, dtype, full_scale, out, minimum, maximum)
         return result
 
     def simplify(self, eps=1e-15):
@@ -2023,7 +2085,7 @@ class RealWaveVStack(_RealWaveVStackBase):
     def __getstate__(self):
         return (self._core.to_bytes(), self.start, self.stop,
                 self.sample_rate, self.offset, self._shift_tick,
-                self.filters, self.nonlinear, self.label, self.min, self.max)
+                self._filters, self.nonlinear, self.label, self.min, self.max)
 
     def __setstate__(self, state):
         _ensure_c_clock_locked()

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: waveforms
-Version: 3.6.1
+Version: 3.7.0
 Summary: Edit waveforms used in experiment
 Author-email: feihoo87 <feihoo87@gmail.com>
 Maintainer-email: feihoo87 <feihoo87@gmail.com>
@@ -202,14 +202,37 @@ 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).
 

{waveforms-3.6.1 → waveforms-3.7.0}/waveforms.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ pyproject.toml
 setup.py
 tests/test_common_pipeline.py
 tests/test_core.py
+tests/test_filter_parameters.py
 tests/test_native_sos.py
 tests/test_nonlinear.py
 tests/test_output_limits.py