waveforms 3.5.0__tar.gz → 3.5.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: waveforms
-Version: 3.5.0
+Version: 3.5.1
 Summary: Edit waveforms used in experiment
 Author-email: feihoo87 <feihoo87@gmail.com>
 Maintainer-email: feihoo87 <feihoo87@gmail.com>
@@ -180,12 +180,44 @@ flux_samples = trajectory.sample(dtype=np.int16)
 ```
 
 The sampling order is waveform accumulation, nonlinear mapping, optional SOS
-filtering/predistortion, and finally integer quantization. This is important for
+filtering/predistortion, output amplitude limits (`min`/`max`), and finally
+integer quantization or floating-point output. This is important for
 `WaveVStack`: the map is applied to the accumulated trajectory rather than to
 each pulse event independently. `method="linear"` selects the smaller and
 fastest two-point interpolation path. Maps serialize independently through
 `to_bytes()`/`from_bytes()` using the language-neutral `NLM1` format.
 
+Every waveform and stack has output limits, defaulting to `min=-np.inf` and
+`max=np.inf`. A stack ignores its child waveforms' limits and uses only its own:
+
+```python
+stack.min = -0.2
+stack.max = 0.3
+samples = stack.sample()  # limit after the complete calibration/filter chain
+```
+
+Limits apply to whole and chunked sampling, including `out=` buffers and
+integer output. Complex signals limit I and Q independently; `sample_iq()`
+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.
+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.
+`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.
+
 ## Reporting Issues
 Please report all issues [on github](https://github.com/feihoo87/waveforms/issues).
 

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

@@ -136,12 +136,44 @@ flux_samples = trajectory.sample(dtype=np.int16)
 ```
 
 The sampling order is waveform accumulation, nonlinear mapping, optional SOS
-filtering/predistortion, and finally integer quantization. This is important for
+filtering/predistortion, output amplitude limits (`min`/`max`), and finally
+integer quantization or floating-point output. This is important for
 `WaveVStack`: the map is applied to the accumulated trajectory rather than to
 each pulse event independently. `method="linear"` selects the smaller and
 fastest two-point interpolation path. Maps serialize independently through
 `to_bytes()`/`from_bytes()` using the language-neutral `NLM1` format.
 
+Every waveform and stack has output limits, defaulting to `min=-np.inf` and
+`max=np.inf`. A stack ignores its child waveforms' limits and uses only its own:
+
+```python
+stack.min = -0.2
+stack.max = 0.3
+samples = stack.sample()  # limit after the complete calibration/filter chain
+```
+
+Limits apply to whole and chunked sampling, including `out=` buffers and
+integer output. Complex signals limit I and Q independently; `sample_iq()`
+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.
+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.
+`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.
+
 ## Reporting Issues
 Please report all issues [on github](https://github.com/feihoo87/waveforms/issues).
 

waveforms-3.5.1/tests/test_native_sos.py

@@ -0,0 +1,176 @@
+"""Native SOS processing agrees with SciPy and keeps output limits out of state."""
+
+import numpy as np
+import pytest
+from scipy.signal import butter, sosfilt
+
+import waveforms as wf
+from waveforms._waveform import quantize_samples, sosfilt_samples
+
+
+def _clip(values, lower, upper):
+    if np.iscomplexobj(values):
+        return (np.clip(values.real, lower, upper)
+                + 1j * np.clip(values.imag, lower, upper))
+    return np.clip(values, lower, upper)
+
+
+@pytest.mark.parametrize("sections", [1, 2, 4, 8, 16])
+@pytest.mark.parametrize("complex_signal", [False, True])
+def test_scipy_equivalence_and_streaming(sections, complex_signal):
+    rng = np.random.default_rng(832)
+    sos = butter(2 * sections, .2, output="sos")
+    values = rng.normal(size=1031)
+    zi = rng.normal(size=(sections, 2)) * .001
+    initial = .07
+    if complex_signal:
+        values = values + 1j * rng.normal(size=len(values))
+        zi = zi + 1j * rng.normal(size=zi.shape) * .001
+        initial += .04j
+    original = values.copy()
+    initial_state = zi.copy()
+    filtered, expected_state = sosfilt(sos, values - initial, zi=zi)
+    expected = _clip(filtered + initial, -.17, .23)
+    result, state = sosfilt_samples(values, sos, initial, zi,
+                                    lower=-.17, upper=.23)
+    np.testing.assert_allclose(result, expected, rtol=3e-13, atol=3e-14)
+    np.testing.assert_allclose(state, expected_state, rtol=3e-13, atol=3e-14)
+    np.testing.assert_array_equal(zi, initial_state)
+    np.testing.assert_array_equal(values, original)
+
+    # Boundaries straddle the internal block size and include a one-sample chunk.
+    output = np.empty_like(values)
+    state = zi
+    start = 0
+    for stop in (1, 254, 511, 512, 1024, len(values)):
+        part, state = sosfilt_samples(values[start:stop], sos, initial, state,
+                                     lower=-.17, upper=.23,
+                                     out=output[start:stop])
+        assert np.shares_memory(part, output)
+        start = stop
+    np.testing.assert_array_equal(output, result)
+    np.testing.assert_allclose(state, expected_state, rtol=3e-13, atol=3e-14)
+
+
+@pytest.mark.parametrize("bits", [16, 32])
+@pytest.mark.parametrize("sections", [1, 4, 8])
+def test_direct_quantization_matches_scipy(bits, sections):
+    rng = np.random.default_rng(337)
+    values = rng.uniform(-2, 2, 5003)
+    sos = butter(sections * 2, .25, output="sos")
+    expected = quantize_samples(
+        np.clip(sosfilt(sos, values - .1) + .1, -.25, .35), bits, .7)
+    output = np.empty_like(expected)
+    result, _ = sosfilt_samples(values, sos, .1, bits=bits, full_scale=.7,
+                                lower=-.25, upper=.35, out=output)
+    assert result is output
+    np.testing.assert_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("complex_signal", [False, True])
+@pytest.mark.parametrize("overlap", [False, True])
+def test_aliasing_and_readonly_inputs(complex_signal, overlap):
+    rng = np.random.default_rng(4)
+    storage = rng.normal(size=601)
+    if complex_signal:
+        storage = storage + 1j * rng.normal(size=len(storage))
+    values = storage[:-1]
+    output = storage[1:] if overlap else values
+    sos = butter(6, .3, output="sos")
+    sos.flags.writeable = False
+    # SciPy 1.13 requires a writable coefficient buffer.
+    expected = sosfilt(sos.copy(), values.copy())
+    result, _ = sosfilt_samples(values, sos, out=output)
+    assert result is output
+    np.testing.assert_allclose(result, expected, rtol=3e-13, atol=3e-14)
+    values.flags.writeable = False
+    expected = sosfilt(sos.copy(), values.copy())
+    result, _ = sosfilt_samples(values, sos)
+    np.testing.assert_allclose(result, expected, rtol=3e-13, atol=3e-14)
+
+
+def test_coefficients_may_overlap_output():
+    sos = butter(8, .3, output="sos")
+    values = np.linspace(-1, 1, sos.size)
+    expected = sosfilt(sos.copy(), values)
+    result, _ = sosfilt_samples(values, sos, out=sos.reshape(-1))
+    np.testing.assert_allclose(result, expected, rtol=3e-13, atol=3e-14)
+
+
+@pytest.mark.parametrize("dtype", [np.float64, np.complex128])
+def test_empty_input_preserves_state(dtype):
+    sos = butter(4, .3, output="sos")
+    zi = np.ones((2, 2), dtype=dtype)
+    result, state = sosfilt_samples(np.empty(0, dtype=dtype), sos, zi=zi)
+    assert result.shape == (0,)
+    assert result.dtype == dtype
+    np.testing.assert_array_equal(state, zi)
+
+
+@pytest.mark.parametrize("sos", [np.ones((2, 5)), np.ones((1, 2, 6)),
+                                  [[1, 0, 0, 2, 0, 0]]])
+def test_invalid_coefficients(sos):
+    with pytest.raises(ValueError, match="sos"):
+        sosfilt_samples(np.ones(3), sos)
+
+
+def test_invalid_state_and_output():
+    sos = butter(4, .3, output="sos")
+    values = np.ones(10)
+    with pytest.raises(ValueError, match="zi"):
+        sosfilt_samples(values, sos, zi=np.zeros((1, 2)))
+    with pytest.raises(ValueError, match="shape"):
+        sosfilt_samples(values, sos, out=np.empty(9))
+    with pytest.raises(TypeError, match="dtype"):
+        sosfilt_samples(values, sos, bits=16, out=np.empty(10))
+    with pytest.raises(ValueError, match="contiguous"):
+        sosfilt_samples(values, sos, bits=16, out=np.empty(20, dtype=np.int16)[::2])
+    with pytest.raises(TypeError, match="real signal"):
+        sosfilt_samples(values + 1j, sos, bits=16)
+    with pytest.raises(ValueError, match="full_scale"):
+        sosfilt_samples(values, sos, bits=16, full_scale=0)
+    with pytest.raises(ValueError, match="min and max"):
+        sosfilt_samples(values, sos, lower=np.nan)
+    with pytest.raises(ValueError, match="non-finite"):
+        sosfilt_samples(np.array([np.nan]), sos, bits=16)
+
+
+def _wave():
+    wave = .4 + .5 * wf.cos(6 * np.pi)
+    wave.start, wave.stop, wave.sample_rate = 0., 1., 1024
+    wave.min, wave.max = -.15, .27
+    return wave
+
+
+@pytest.mark.parametrize("coefficient_dtype", [np.complex128, np.longdouble])
+def test_scipy_fallback(coefficient_dtype):
+    wave = _wave()
+    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)
+
+
+def test_pipeline_output_casting_and_single_section_vector():
+    wave = _wave()
+    wave.filters = butter(2, .3, output="sos")[0], .03
+    expected = wave.sample()
+    for dtype in (None, np.float32, np.float64):
+        for stride in (1, 2):
+            output = np.empty(1024 * stride)[::stride]
+            result = wave.sample(dtype=dtype, out=output)
+            assert result is output
+            np.testing.assert_array_equal(result, expected.astype(dtype or np.float64))
+    expected_i16 = quantize_samples(expected, 16)
+    np.testing.assert_array_equal(wave.sample(dtype=np.int16), expected_i16)
+    np.testing.assert_allclose(np.concatenate(list(wave.sample(chunk_size=31))),
+                               expected, rtol=3e-13, atol=3e-14)
+    with pytest.raises(TypeError, match="dtype"):
+        wave.sample(dtype=np.int16, out=np.empty(1024))
+    with pytest.raises(ValueError, match="contiguous"):
+        wave.sample(out=np.empty(2048, dtype=np.int16)[::2])

waveforms-3.5.1/tests/test_output_limits.py

@@ -0,0 +1,252 @@
+"""Output limits belong after calibration/filtering, before DAC conversion."""
+
+import pickle
+
+import numpy as np
+import pytest
+from scipy.signal import sosfilt
+
+import waveforms as wf
+from waveforms._waveform import quantize_samples
+
+
+def _configure(wave, rate=128):
+    wave.start = 0.0
+    wave.stop = 1.0
+    wave.sample_rate = rate
+    return wave
+
+
+def _signal(kind):
+    real = 0.45 + 0.35 * wf.cos(6 * np.pi)
+    imag = -0.3 + 0.2 * wf.sin(4 * np.pi)
+    if kind == "real":
+        return real
+    if kind == "complex":
+        # Component limits must not truncate a later calibration/filter input.
+        real.min, real.max = -0.01, 0.01
+        imag.min, imag.max = -0.01, 0.01
+        return wf.ComplexWaveform(real, imag)
+    real_children = [0.6 * real, 0.4 * real]
+    imag_children = [0.3 * imag, 0.7 * imag]
+    for child in real_children + imag_children:
+        child.min, child.max = -0.01, 0.01
+    real_stack = wf.WaveVStack(real_children)
+    if kind == "stack":
+        return real_stack
+    imag_stack = wf.WaveVStack(imag_children)
+    real_stack.min, real_stack.max = -0.02, 0.02
+    imag_stack.min, imag_stack.max = -0.02, 0.02
+    return wf.ComplexWaveVStack(real_stack, imag_stack)
+
+
+def _clip(values, lower, upper):
+    if np.iscomplexobj(values):
+        return (np.clip(values.real, lower, upper)
+                + 1j * np.clip(values.imag, lower, upper))
+    return np.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):
+    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)
+    mapping = wf.NonlinearMap.from_samples(
+        [-3., 3.], [-6., 6.], method="linear", table_size=2)
+    wave.nonlinear = (mapping, mapping) if "complex" in kind else mapping
+
+    positions = np.arange(0., 1., 1 / rate)
+    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))
+    filtered = sosfilt(sos, 2 * raw - initial) + initial
+    expected = _clip(filtered, wave.min, wave.max)
+
+    np.testing.assert_allclose(wave.sample(), expected, rtol=2e-13, atol=2e-14)
+    chunks = list(wave.sample(chunk_size=13))
+    np.testing.assert_allclose(np.concatenate(chunks), expected,
+                               rtol=2e-13, atol=2e-14)
+    target = np.empty_like(expected)
+    assert wave.sample(out=target) is target
+    np.testing.assert_allclose(target, expected, rtol=2e-13, atol=2e-14)
+    restored = pickle.loads(pickle.dumps(wave))
+    np.testing.assert_array_equal(restored.sample(), wave.sample())
+
+    if "complex" in kind:
+        for dtype, bits in ((np.int16, 16), (np.int32, 32)):
+            targets = tuple(np.empty(len(expected), dtype=dtype) for _ in range(2))
+            actual = wave.sample_iq(dtype=dtype, full_scale=0.7, out=targets)
+            for result, output, component in zip(actual, targets,
+                                                  (expected.real, expected.imag)):
+                assert result is output
+                np.testing.assert_array_equal(
+                    result, quantize_samples(component, bits, 0.7))
+            iq_chunks = list(wave.sample_iq(
+                dtype=dtype, full_scale=0.7, chunk_size=13, out=targets))
+            for index, component in enumerate((expected.real, expected.imag)):
+                np.testing.assert_array_equal(
+                    np.concatenate([chunk[index] for chunk in iq_chunks]),
+                    quantize_samples(component, bits, 0.7))
+    else:
+        for dtype, bits in ((np.int16, 16), (np.int32, 32)):
+            expected_integer = quantize_samples(expected, bits, 0.7)
+            target = np.empty(len(expected), dtype=dtype)
+            assert wave.sample(out=target, full_scale=0.7) is target
+            np.testing.assert_array_equal(target, expected_integer)
+            chunks = wave.sample(out=target, chunk_size=13, full_scale=0.7)
+            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))
+    wave.min, wave.max = -.2, .2
+    wave.filters = (np.array([[gain, 0., 0., 1., 0., 0.]]), 0.)
+    np.testing.assert_allclose(wave.sample(), expected)
+    np.testing.assert_allclose(np.concatenate(list(wave.sample(chunk_size=7))), expected)
+
+
+@pytest.mark.parametrize("kind", ["real", "stack", "complex", "complex_stack"])
+def test_limits_cannot_hide_nonlinear_domain_errors(kind):
+    wave = _configure(_signal(kind))
+    wave.min, wave.max = -.1, .1
+    mapping = wf.NonlinearMap.from_samples([-.2, .2], [-.2, .2], method="linear")
+    wave.nonlinear = (mapping, mapping) if "complex" in kind else mapping
+    with pytest.raises(ValueError, match="outside its domain"):
+        wave.sample()
+    with pytest.raises(ValueError, match="outside its domain"):
+        list(wave.sample(chunk_size=7))
+
+
+@pytest.mark.parametrize("rate", [2_400_000_000, 7_000_000_000])
+@pytest.mark.parametrize("spacing", [2e-9, 40e-9])
+@pytest.mark.parametrize("many_scales", [False, True])
+@pytest.mark.parametrize("limits", [(-.18, .26), (.08, .26), (-.3, -.1)])
+def test_stack_native_limits_after_overlap_and_before_quantization(
+        rate, spacing, many_scales, limits):
+    pulse = wf.gaussian(20e-9)
+    pulse.min, pulse.max = -.001, .001
+    scales = np.linspace(-.9, .9, 80) if many_scales else np.resize([-.6, .4, .8], 80)
+    stack = wf.WaveVStack.from_events(
+        [pulse], np.zeros(80, dtype=np.uint32),
+        np.arange(80, dtype=np.int64) * wf.time_to_tick(spacing), scales)
+    stack.offset = .03
+    stack.start, stack.stop = -30e-9, 80 * spacing + 30e-9
+    stack.sample_rate = rate
+    raw = stack.sample()
+    plan = stack._sample_plan_cache[1]
+    stack.min, stack.max = limits
+    expected = np.clip(raw, *limits)
+    np.testing.assert_array_equal(stack.sample(), expected)
+    # Limits are execution parameters: changing them must not rebuild the plan.
+    assert stack._sample_plan_cache[1] is plan
+    np.testing.assert_allclose(np.concatenate(list(stack.sample(chunk_size=137))),
+                               expected, rtol=2e-13, atol=2e-14)
+    for dtype, bits in ((np.int16, 16), (np.int32, 32)):
+        expected_integer = quantize_samples(expected, bits, .7)
+        out = np.empty(len(raw), dtype=dtype)
+        assert stack.sample(dtype=dtype, out=out, full_scale=.7) is out
+        np.testing.assert_array_equal(out, expected_integer)
+    stack.min, stack.max = -np.inf, np.inf
+    np.testing.assert_array_equal(stack.sample(), raw)
+
+
+@pytest.mark.parametrize("kind", ["stack", "complex_stack"])
+def test_stack_owns_limits_and_preserves_them_in_pickle_and_shift(kind):
+    stack = _configure(_signal(kind))
+    assert stack.min == -np.inf and stack.max == np.inf
+    raw = stack.sample()
+    stack.min, stack.max = -.17, .23
+    expected = _clip(raw, stack.min, stack.max)
+    np.testing.assert_array_equal(stack.sample(), expected)
+    shifted = stack >> 0.0
+    assert (shifted.min, shifted.max) == (-.17, .23)
+    np.testing.assert_array_equal(shifted.sample(), expected)
+    restored = pickle.loads(pickle.dumps(stack))
+    assert (restored.min, restored.max) == (-.17, .23)
+    np.testing.assert_array_equal(restored.sample(), expected)
+    # Legacy states omit limits, and the oldest also omit the nonlinear map.
+    state = stack.__getstate__()[:-2]
+    for legacy in (state, state[:-2] + state[-1:]):
+        restored = type(stack).__new__(type(stack))
+        restored.__setstate__(legacy)
+        assert restored.min == -np.inf and restored.max == np.inf
+        np.testing.assert_array_equal(restored.sample(), raw)
+
+
+@pytest.mark.parametrize("kind", ["stack", "complex_stack"])
+def test_stack_direct_evaluation_limits_only_its_own_contribution(kind):
+    stack = _signal(kind)
+    positions = np.array([.013, .129, .44])
+    raw = stack(positions)
+    stack.min, stack.max = -.17, .23
+    expected = _clip(raw, stack.min, stack.max)
+    output = np.full_like(raw, 3)
+    assert stack(positions, out=output, accumulate=True) is output
+    np.testing.assert_allclose(output, 3 + expected)
+    np.testing.assert_allclose(stack(float(positions[0])), expected[0])
+
+
+def test_empty_stack_limits_apply_to_idle_and_float_output_buffers():
+    stack = _configure(wf.WaveVStack())
+    stack.min, stack.max = .13, .27
+    for dtype in (np.float32, np.float64, np.int16, np.int32):
+        target = np.empty(128, dtype=dtype)
+        result = stack.sample(dtype=dtype, out=target)
+        assert result is target
+        if np.issubdtype(dtype, np.integer):
+            expected = quantize_samples(np.full(128, .13), np.iinfo(dtype).bits)
+        else:
+            expected = np.full(128, .13, dtype=dtype)
+        np.testing.assert_array_equal(result, expected)
+    stack.stop = stack.start
+    assert stack.sample(dtype=np.int16).size == 0
+
+
+@pytest.mark.parametrize("kind", ["real", "stack", "complex", "complex_stack"])
+@pytest.mark.parametrize("bounds", [
+    (1., -1.), (np.nan, 1.), (-1., np.nan), (np.inf, np.inf), (-np.inf, -np.inf),
+])
+def test_invalid_output_limits_are_rejected(kind, bounds):
+    wave = _configure(_signal(kind))
+    wave.min, wave.max = bounds
+    with pytest.raises(ValueError, match="min and max"):
+        wave.sample()
+
+
+@pytest.mark.parametrize("rate", [2_400_000_000, 7_000_000_000])
+@pytest.mark.parametrize("bits", [16, 32])
+def test_integer_limit_rounding_at_half_codes_and_beyond_full_scale(rate, bits):
+    wave = wf.WaveVStack([wf.square(20e-9), -wf.square(20e-9) >> 40e-9])
+    wave.start, wave.stop, wave.sample_rate = -30e-9, 70e-9, rate
+    raw = wave.sample()
+    full_scale = .7
+    code = full_scale / (2 ** (bits - 1))
+    dtype = np.int16 if bits == 16 else np.int32
+    for lower, upper in ((-.5 * code, 2.5 * code), (.8, 1.1), (-1.1, -.8),
+                         (-np.inf, .2), (-.2, np.inf), (.1, .1)):
+        wave.min, wave.max = lower, upper
+        np.testing.assert_array_equal(
+            wave.sample(dtype=dtype, full_scale=full_scale),
+            quantize_samples(np.clip(raw, lower, upper), bits, full_scale))
+
+
+def test_many_scale_native_limits_span_scratch_blocks_and_partial_placements():
+    wave = wf.WaveVStack.from_events(
+        [wf.gaussian(300e-9)], np.zeros(80, dtype=np.uint32),
+        np.arange(80, dtype=np.int64) * wf.time_to_tick(600e-9),
+        np.linspace(-.9, .9, 80))
+    wave.start, wave.stop = 47e-9, 79 * 600e-9 + 73e-9
+    wave.sample_rate = 2_400_000_000
+    raw = wave.sample()
+    wave.min, wave.max = -.17, .23
+    for dtype, bits in ((np.int16, 16), (np.int32, 32)):
+        np.testing.assert_array_equal(
+            wave.sample(dtype=dtype, full_scale=.7),
+            quantize_samples(np.clip(raw, -.17, .23), bits, .7))

waveforms-3.5.1/waveforms/WaveformLexer.py

@@ -0,0 +1,134 @@
+# Generated from Waveform.g4 by ANTLR 4.13.2
+from antlr4 import *
+from io import StringIO
+import sys
+if sys.version_info[1] > 5:
+    from typing import TextIO
+else:
+    from typing.io import TextIO
+
+
+def serializedATN():
+    return [
+        4,0,22,169,6,-1,2,0,7,0,2,1,7,1,2,2,7,2,2,3,7,3,2,4,7,4,2,5,7,5,
+        2,6,7,6,2,7,7,7,2,8,7,8,2,9,7,9,2,10,7,10,2,11,7,11,2,12,7,12,2,
+        13,7,13,2,14,7,14,2,15,7,15,2,16,7,16,2,17,7,17,2,18,7,18,2,19,7,
+        19,2,20,7,20,2,21,7,21,2,22,7,22,1,0,1,0,1,1,1,1,1,2,1,2,1,3,1,3,
+        1,4,1,4,1,5,1,5,1,6,1,6,1,7,1,7,1,8,1,8,1,9,1,9,1,10,1,10,1,11,1,
+        11,1,11,3,11,73,8,11,1,12,4,12,76,8,12,11,12,12,12,77,1,12,1,12,
+        5,12,82,8,12,10,12,12,12,85,9,12,3,12,87,8,12,1,12,1,12,4,12,91,
+        8,12,11,12,12,12,92,3,12,95,8,12,1,12,1,12,3,12,99,8,12,1,12,4,12,
+        102,8,12,11,12,12,12,103,3,12,106,8,12,1,13,4,13,109,8,13,11,13,
+        12,13,110,1,14,1,14,3,14,115,8,14,1,14,1,14,1,15,1,15,5,15,121,8,
+        15,10,15,12,15,124,9,15,1,15,1,15,1,15,5,15,129,8,15,10,15,12,15,
+        132,9,15,1,15,3,15,135,8,15,1,16,1,16,1,16,1,16,1,16,1,16,3,16,143,
+        8,16,1,17,1,17,5,17,147,8,17,10,17,12,17,150,9,17,1,18,1,18,1,18,
+        1,19,1,19,1,19,1,20,1,20,1,20,1,21,4,21,162,8,21,11,21,12,21,163,
+        1,21,1,21,1,22,1,22,0,0,23,1,1,3,2,5,3,7,4,9,5,11,6,13,7,15,8,17,
+        9,19,10,21,11,23,12,25,13,27,14,29,15,31,16,33,17,35,18,37,19,39,
+        20,41,21,43,22,45,0,1,0,8,2,0,69,69,101,101,2,0,43,43,45,45,3,0,
+        10,10,13,13,34,34,3,0,10,10,13,13,39,39,3,0,65,90,95,95,97,122,4,
+        0,48,57,65,90,95,95,97,122,3,0,9,10,13,13,32,32,1,0,48,57,186,0,
+        1,1,0,0,0,0,3,1,0,0,0,0,5,1,0,0,0,0,7,1,0,0,0,0,9,1,0,0,0,0,11,1,
+        0,0,0,0,13,1,0,0,0,0,15,1,0,0,0,0,17,1,0,0,0,0,19,1,0,0,0,0,21,1,
+        0,0,0,0,23,1,0,0,0,0,25,1,0,0,0,0,27,1,0,0,0,0,29,1,0,0,0,0,31,1,
+        0,0,0,0,33,1,0,0,0,0,35,1,0,0,0,0,37,1,0,0,0,0,39,1,0,0,0,0,41,1,
+        0,0,0,0,43,1,0,0,0,1,47,1,0,0,0,3,49,1,0,0,0,5,51,1,0,0,0,7,53,1,
+        0,0,0,9,55,1,0,0,0,11,57,1,0,0,0,13,59,1,0,0,0,15,61,1,0,0,0,17,
+        63,1,0,0,0,19,65,1,0,0,0,21,67,1,0,0,0,23,72,1,0,0,0,25,94,1,0,0,
+        0,27,108,1,0,0,0,29,114,1,0,0,0,31,134,1,0,0,0,33,142,1,0,0,0,35,
+        144,1,0,0,0,37,151,1,0,0,0,39,154,1,0,0,0,41,157,1,0,0,0,43,161,
+        1,0,0,0,45,167,1,0,0,0,47,48,5,61,0,0,48,2,1,0,0,0,49,50,5,94,0,
+        0,50,4,1,0,0,0,51,52,5,42,0,0,52,6,1,0,0,0,53,54,5,47,0,0,54,8,1,
+        0,0,0,55,56,5,43,0,0,56,10,1,0,0,0,57,58,5,45,0,0,58,12,1,0,0,0,
+        59,60,5,40,0,0,60,14,1,0,0,0,61,62,5,41,0,0,62,16,1,0,0,0,63,64,
+        5,44,0,0,64,18,1,0,0,0,65,66,5,91,0,0,66,20,1,0,0,0,67,68,5,93,0,
+        0,68,22,1,0,0,0,69,73,3,25,12,0,70,73,3,27,13,0,71,73,3,29,14,0,
+        72,69,1,0,0,0,72,70,1,0,0,0,72,71,1,0,0,0,73,24,1,0,0,0,74,76,3,
+        45,22,0,75,74,1,0,0,0,76,77,1,0,0,0,77,75,1,0,0,0,77,78,1,0,0,0,
+        78,86,1,0,0,0,79,83,5,46,0,0,80,82,3,45,22,0,81,80,1,0,0,0,82,85,
+        1,0,0,0,83,81,1,0,0,0,83,84,1,0,0,0,84,87,1,0,0,0,85,83,1,0,0,0,
+        86,79,1,0,0,0,86,87,1,0,0,0,87,95,1,0,0,0,88,90,5,46,0,0,89,91,3,
+        45,22,0,90,89,1,0,0,0,91,92,1,0,0,0,92,90,1,0,0,0,92,93,1,0,0,0,
+        93,95,1,0,0,0,94,75,1,0,0,0,94,88,1,0,0,0,95,105,1,0,0,0,96,98,7,
+        0,0,0,97,99,7,1,0,0,98,97,1,0,0,0,98,99,1,0,0,0,99,101,1,0,0,0,100,
+        102,3,45,22,0,101,100,1,0,0,0,102,103,1,0,0,0,103,101,1,0,0,0,103,
+        104,1,0,0,0,104,106,1,0,0,0,105,96,1,0,0,0,105,106,1,0,0,0,106,26,
+        1,0,0,0,107,109,3,45,22,0,108,107,1,0,0,0,109,110,1,0,0,0,110,108,
+        1,0,0,0,110,111,1,0,0,0,111,28,1,0,0,0,112,115,3,25,12,0,113,115,
+        3,27,13,0,114,112,1,0,0,0,114,113,1,0,0,0,115,116,1,0,0,0,116,117,
+        5,106,0,0,117,30,1,0,0,0,118,122,5,34,0,0,119,121,8,2,0,0,120,119,
+        1,0,0,0,121,124,1,0,0,0,122,120,1,0,0,0,122,123,1,0,0,0,123,125,
+        1,0,0,0,124,122,1,0,0,0,125,135,5,34,0,0,126,130,5,39,0,0,127,129,
+        8,3,0,0,128,127,1,0,0,0,129,132,1,0,0,0,130,128,1,0,0,0,130,131,
+        1,0,0,0,131,133,1,0,0,0,132,130,1,0,0,0,133,135,5,39,0,0,134,118,
+        1,0,0,0,134,126,1,0,0,0,135,32,1,0,0,0,136,137,5,112,0,0,137,143,
+        5,105,0,0,138,143,5,101,0,0,139,140,5,105,0,0,140,141,5,110,0,0,
+        141,143,5,102,0,0,142,136,1,0,0,0,142,138,1,0,0,0,142,139,1,0,0,
+        0,143,34,1,0,0,0,144,148,7,4,0,0,145,147,7,5,0,0,146,145,1,0,0,0,
+        147,150,1,0,0,0,148,146,1,0,0,0,148,149,1,0,0,0,149,36,1,0,0,0,150,
+        148,1,0,0,0,151,152,5,42,0,0,152,153,5,42,0,0,153,38,1,0,0,0,154,
+        155,5,60,0,0,155,156,5,60,0,0,156,40,1,0,0,0,157,158,5,62,0,0,158,
+        159,5,62,0,0,159,42,1,0,0,0,160,162,7,6,0,0,161,160,1,0,0,0,162,
+        163,1,0,0,0,163,161,1,0,0,0,163,164,1,0,0,0,164,165,1,0,0,0,165,
+        166,6,21,0,0,166,44,1,0,0,0,167,168,7,7,0,0,168,46,1,0,0,0,18,0,
+        72,77,83,86,92,94,98,103,105,110,114,122,130,134,142,148,163,1,6,
+        0,0
+    ]
+
+class WaveformLexer(Lexer):
+
+    atn = ATNDeserializer().deserialize(serializedATN())
+
+    decisionsToDFA = [ DFA(ds, i) for i, ds in enumerate(atn.decisionToState) ]
+
+    T__0 = 1
+    T__1 = 2
+    T__2 = 3
+    T__3 = 4
+    T__4 = 5
+    T__5 = 6
+    T__6 = 7
+    T__7 = 8
+    T__8 = 9
+    T__9 = 10
+    T__10 = 11
+    NUMBER = 12
+    REAL = 13
+    INT = 14
+    IMAG = 15
+    STRING = 16
+    CONSTANT = 17
+    ID = 18
+    POW = 19
+    LSHIFT = 20
+    RSHIFT = 21
+    WS = 22
+
+    channelNames = [ u"DEFAULT_TOKEN_CHANNEL", u"HIDDEN" ]
+
+    modeNames = [ "DEFAULT_MODE" ]
+
+    literalNames = [ "<INVALID>",
+            "'='", "'^'", "'*'", "'/'", "'+'", "'-'", "'('", "')'", "','", 
+            "'['", "']'", "'**'", "'<<'", "'>>'" ]
+
+    symbolicNames = [ "<INVALID>",
+            "NUMBER", "REAL", "INT", "IMAG", "STRING", "CONSTANT", "ID", 
+            "POW", "LSHIFT", "RSHIFT", "WS" ]
+
+    ruleNames = [ "T__0", "T__1", "T__2", "T__3", "T__4", "T__5", "T__6", 
+                  "T__7", "T__8", "T__9", "T__10", "NUMBER", "REAL", "INT", 
+                  "IMAG", "STRING", "CONSTANT", "ID", "POW", "LSHIFT", "RSHIFT", 
+                  "WS", "DIGIT" ]
+
+    grammarFileName = "Waveform.g4"
+
+    def __init__(self, input=None, output:TextIO = sys.stdout):
+        super().__init__(input, output)
+        self.checkVersion("4.13.2")
+        self._interp = LexerATNSimulator(self, self.atn, self.decisionsToDFA, PredictionContextCache())
+        self._actions = None
+        self._predicates = None
+
+