waveforms 3.5.1__tar.gz → 3.6.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: waveforms
-Version: 3.5.1
+Version: 3.6.1
 Summary: Edit waveforms used in experiment
 Author-email: feihoo87 <feihoo87@gmail.com>
 Maintainer-email: feihoo87 <feihoo87@gmail.com>
@@ -213,10 +213,17 @@ 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.
+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.6.1}/README.md

@@ -169,10 +169,17 @@ 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.
+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.6.1/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.6.1/tests/test_simd_sampling.py

@@ -0,0 +1,136 @@
+"""Numerical boundaries for native SIMD quantization and table loads."""
+
+import pickle
+
+import numpy as np
+import pytest
+
+import waveforms as wf
+from waveforms._waveform import quantize_samples
+
+
+def reference_quantize(values, bits, full_scale):
+    limit = float(1 << (bits - 1))
+    scaled = np.clip(values * (limit / full_scale), -limit, limit - 1)
+    integral = np.trunc(scaled)
+    rounded = integral + np.copysign(
+        (np.abs(scaled - integral) >= .5).astype(float), scaled)
+    return rounded.astype(np.int16 if bits == 16 else np.int32)
+
+
+@pytest.mark.parametrize('bits', [16, 32])
+@pytest.mark.parametrize('full_scale', [1., .7, 2., 1e-100, 1e100])
+def test_quantization_half_lsb_neighbors_tails_and_saturation(bits, full_scale):
+    limit = float(1 << (bits - 1))
+    halves = np.array([.5, 1.5, 2.5, 127.5, limit - 1.5])
+    steps = np.concatenate([np.nextafter(halves, 0), halves,
+                            np.nextafter(halves, np.inf)])
+    values = np.concatenate([steps, -steps, [-2 * limit, 2 * limit, 0., -0.]])
+    values *= full_scale / limit
+    # Rotate the half-LSB neighbors through every SIMD lane and the tail.
+    for count in (0, 1, 3, 4, 7, 8, 9, 15, 16, 17, 31, 32, 33, 65, 257):
+        for shift in range(8):
+            source = np.resize(np.roll(values, shift), count)
+            expected = reference_quantize(source, bits, full_scale)
+            padded = np.full(count + 2, 123, dtype=expected.dtype)
+            output = padded[1:-1]  # Not 16/32/64-byte aligned.
+            assert quantize_samples(source, bits, full_scale, out=output) is output
+            np.testing.assert_array_equal(output, expected)
+            assert padded[0] == padded[-1] == 123
+
+
+@pytest.mark.parametrize('bits', [16, 32])
+def test_nonfinite_quantization_in_each_vector_lane_and_tail(bits):
+    for count in (16, 33, 257):
+        for lane in range(count):
+            source = np.zeros(count)
+            source[lane] = [np.nan, np.inf, -np.inf][lane % 3]
+            with pytest.raises(ValueError):
+                quantize_samples(source, bits)
+
+
+@pytest.mark.parametrize('storage', [np.float32, np.float64])
+@pytest.mark.parametrize('method', ['linear', 'monotone_cubic'])
+def test_table_loads_random_intervals_endpoints_and_aliasing(storage, method):
+    rng = np.random.default_rng(7428)
+    for table_size in (2, 3, 17, 4097):
+        mapping = wf.NonlinearMap.from_samples(
+            [-1., -.73, -.11, .29, 1.], [-.9, -.79, -.25, .42, .96],
+            method=method, dtype=storage, table_size=table_size,
+            extrapolate='clip')
+        for count in (7, 8, 9, 15, 16, 17, 31, 32, 33, 257):
+            source = rng.uniform(-1.2, 1.2, count)
+            source[::4] = -1.
+            source[1::4] = 1.
+            expected = np.array([mapping(float(value)) for value in source])
+            padded = np.full(count + 2, 123.)
+            output = padded[1:-1]
+            mapping(source, out=output)
+            np.testing.assert_allclose(output, expected, rtol=2e-15, atol=2e-15)
+            assert padded[0] == padded[-1] == 123.
+            mapping(source, out=source)
+            np.testing.assert_array_equal(source, output)
+
+
+@pytest.mark.parametrize('bits', [16, 32])
+@pytest.mark.parametrize('varied', [False, True])
+@pytest.mark.parametrize('limited', [False, True])
+@pytest.mark.parametrize('offset', [0., .07])
+def test_stack_template_quantization_blocks_and_clipped_placements(
+        bits, varied, limited, offset):
+    events = 101
+    pulse = .9 * wf.gaussian(300e-9)
+    scales = (np.linspace(-.9, .9, events) if varied else
+              np.resize([.5, -.75, 1.], events))
+    stack = wf.WaveVStack.from_events(
+        [pulse], np.zeros(events, dtype=np.uint32),
+        np.arange(events, dtype=np.int64) * wf.time_to_tick(600e-9), scales)
+    stack.start, stack.stop = 0., (events - 1) * 600e-9
+    stack.sample_rate = 2_400_000_000
+    stack.offset = offset
+    if limited:
+        stack.min, stack.max = -.3, .35
+    restored = pickle.loads(pickle.dumps(stack)) >> (7 / 120e9)
+    expected = reference_quantize(restored.sample(), bits, .7)
+    np.testing.assert_array_equal(restored.sample(dtype=expected.dtype, full_scale=.7), expected)
+    output = np.empty_like(expected)
+    assert restored.sample(out=output, full_scale=.7) is output
+    np.testing.assert_array_equal(output, expected)
+
+
+@pytest.mark.parametrize('block', [None, -200e6, 80e6])
+@pytest.mark.parametrize('width', [12e-9, 20e-9, 1000e-9])
+def test_drag_vector_evaluation_and_cold_template_plan(block, width):
+    templates = [.4 * wf.drag(5e9, width, delta=-200e6, block_freq=block,
+                             phase=index * .371, t0=3e-9)
+                 for index in range(9)]
+    pulse = templates[3] >> (7 / 120e9)
+    positions = np.linspace(-width, 2 * width, 1031)
+    scalar = np.array([pulse(float(position)) for position in positions])
+    np.testing.assert_allclose(pulse(positions), scalar, rtol=2e-14, atol=2e-14)
+    # Tick residues exercise different sampling phases and clipping at both
+    # ends; the old event evaluator provides an independent scalar reference.
+    delays = (np.arange(31, dtype=np.int64) * wf.time_to_tick(3 * width)
+              + np.arange(31) % 50)
+    stack = wf.WaveVStack.from_events(
+        templates, np.arange(31, dtype=np.uint32) % len(templates), delays,
+        np.resize([.5, -.75, 1.], 31))
+    stack.start, stack.stop = 0., 90 * width
+    stack.sample_rate = 2_400_000_000
+    restored = pickle.loads(pickle.dumps(stack)) >> (7 / 120e9)
+    block_before_sampling = restored.to_bytes()
+    count = len(restored.sample())
+    scalar = restored._core.sample(0, count, 50, 1, 7, 0.)
+    np.testing.assert_allclose(restored.sample(), scalar, rtol=2e-14, atol=2e-14)
+    for bits in (16, 32):
+        expected = reference_quantize(scalar, bits, 1.)
+        np.testing.assert_array_equal(restored.sample(dtype=expected.dtype), expected)
+    assert restored.to_bytes() == block_before_sampling
+
+
+def test_drag_plan_falls_back_for_unsupported_companion_nodes():
+    pulse = wf.drag(5e9, 1e-6, delta=-200e6, block_freq=80e6) * wf.mollifier(1e-6)
+    stack = wf.WaveVStack.from_events([pulse], [0], [0], [.7])
+    stack.start, stack.stop, stack.sample_rate = 0., 1e-6, 2_400_000_000
+    expected = stack._core.sample(0, 2400, 50, 1, 0, 0.)
+    np.testing.assert_array_equal(stack.sample(), expected)

{waveforms-3.5.1 → waveforms-3.6.1}/waveforms/__init__.py

@@ -50,8 +50,10 @@ from .waveform import (
     wave_eval,
     zero,
 )
+from .distortion import drag_fir, exp_decay_filter, exp_decay_filter_from_cascade, exp_decay_filter_to_cascade
 
 __all__ = [
+    "drag_fir", "exp_decay_filter", "exp_decay_filter_from_cascade", "exp_decay_filter_to_cascade",
     "ComplexWaveform", "ComplexWaveVStack", "D", "NonlinearMap", "RealWaveform",
     "RealWaveVStack", "Waveform", "WaveVStack",
     "chirp", "const", "cos", "cosh",