waveforms 3.2.0__tar.gz → 3.3.0__tar.gz

{waveforms-3.2.0 → waveforms-3.3.0}/MANIFEST.in

@@ -1,5 +1,3 @@
-include src/*.h
-include src/*.c
 include waveforms/_cwaveform.h
 include waveforms/_cwaveform.c
 include waveforms/_cwaveform.md

{waveforms-3.2.0/waveforms.egg-info → waveforms-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: waveforms
-Version: 3.2.0
+Version: 3.3.0
 Summary: Edit waveforms used in experiment
 Author-email: feihoo87 <feihoo87@gmail.com>
 Maintainer-email: feihoo87 <feihoo87@gmail.com>
@@ -98,11 +98,13 @@ plt.plot(t, y_wav(t))
 plt.show()
 ```
 
-### Packed binary representation
+### Unified binary representation
 
-Starting with version 3, `Waveform` and `WaveVStack` use a packed-binary backend.
-It is intended for workloads with many small pulses and for low-overhead
-serialization.
+`Waveform` is the common base class for every signal object. `RealWaveform`
+and `ComplexWaveform` are concrete waveforms; `WaveVStack` is the common stack
+base, with `RealWaveVStack` and `ComplexWaveVStack` as its concrete forms.
+The original construction style remains unchanged and automatically selects
+the compact C core for common pulses and repeated-pulse stacks:
 
 ```python
 import waveforms as wf
@@ -114,12 +116,17 @@ import waveforms as wf
 pulse = (wf.gaussian(12e-9) >> 20e-9) * wf.cos(2 * wf.pi * 5e9)
 data = pulse.to_bytes()
 restored = wf.Waveform.from_bytes(data)
+
+assert isinstance(pulse, wf.Waveform)
+stack = wf.WaveVStack([pulse, pulse >> 40e-9])
+assert isinstance(stack, wf.RealWaveVStack)
+assert isinstance(stack, wf.WaveVStack)
 ```
 
-Time resolution is process-wide and is not stored in each binary block. A
-process loading a block must therefore use the same resolution as the process
-that created it. The setting is locked when the first waveform object is
-created or loaded.
+The C block format stores signed 64-bit ticks using a process-wide clock. The
+default is 120 GHz. A different process-wide time resolution may be selected
+before the first waveform is constructed; the same C representation and
+evaluator continue to be used. The setting is locked by the first object.
 
 `sample()` has integer-grid fast paths for 500 MHz, 1 GHz, 1.2 GHz, 2 GHz,
 2.4 GHz, 2.5 GHz, 4 GHz, 6 GHz, 8 GHz, and 10 GHz. Real waveforms can be
@@ -131,7 +138,7 @@ pulse.stop = 100e-9
 dac16 = pulse.sample(2_400_000_000, dtype=np.int16, full_scale=1.0)
 ```
 
-The packed core stores and evaluates real-valued signals only. Complex signals
+The low-level cores store and evaluate real-valued signals only. Complex signals
 are represented in Python as independent real and imaginary channels:
 
 ```python
@@ -142,7 +149,7 @@ stack = wf.ComplexWaveVStack([z, z >> 20e-9])
 samples = stack(t)  # complex NumPy array
 ```
 
-`Waveform` and `WaveVStack` therefore avoid complex storage and arithmetic for
+Real waveforms and stacks therefore avoid complex storage and arithmetic for
 the common real-valued case. `ComplexWaveform.real` and `.imag` expose the two
 real channel waveforms.
 

{waveforms-3.2.0 → waveforms-3.3.0}/README.md

@@ -54,11 +54,13 @@ plt.plot(t, y_wav(t))
 plt.show()
 ```
 
-### Packed binary representation
+### Unified binary representation
 
-Starting with version 3, `Waveform` and `WaveVStack` use a packed-binary backend.
-It is intended for workloads with many small pulses and for low-overhead
-serialization.
+`Waveform` is the common base class for every signal object. `RealWaveform`
+and `ComplexWaveform` are concrete waveforms; `WaveVStack` is the common stack
+base, with `RealWaveVStack` and `ComplexWaveVStack` as its concrete forms.
+The original construction style remains unchanged and automatically selects
+the compact C core for common pulses and repeated-pulse stacks:
 
 ```python
 import waveforms as wf
@@ -70,12 +72,17 @@ import waveforms as wf
 pulse = (wf.gaussian(12e-9) >> 20e-9) * wf.cos(2 * wf.pi * 5e9)
 data = pulse.to_bytes()
 restored = wf.Waveform.from_bytes(data)
+
+assert isinstance(pulse, wf.Waveform)
+stack = wf.WaveVStack([pulse, pulse >> 40e-9])
+assert isinstance(stack, wf.RealWaveVStack)
+assert isinstance(stack, wf.WaveVStack)
 ```
 
-Time resolution is process-wide and is not stored in each binary block. A
-process loading a block must therefore use the same resolution as the process
-that created it. The setting is locked when the first waveform object is
-created or loaded.
+The C block format stores signed 64-bit ticks using a process-wide clock. The
+default is 120 GHz. A different process-wide time resolution may be selected
+before the first waveform is constructed; the same C representation and
+evaluator continue to be used. The setting is locked by the first object.
 
 `sample()` has integer-grid fast paths for 500 MHz, 1 GHz, 1.2 GHz, 2 GHz,
 2.4 GHz, 2.5 GHz, 4 GHz, 6 GHz, 8 GHz, and 10 GHz. Real waveforms can be
@@ -87,7 +94,7 @@ pulse.stop = 100e-9
 dac16 = pulse.sample(2_400_000_000, dtype=np.int16, full_scale=1.0)
 ```
 
-The packed core stores and evaluates real-valued signals only. Complex signals
+The low-level cores store and evaluate real-valued signals only. Complex signals
 are represented in Python as independent real and imaginary channels:
 
 ```python
@@ -98,7 +105,7 @@ stack = wf.ComplexWaveVStack([z, z >> 20e-9])
 samples = stack(t)  # complex NumPy array
 ```
 
-`Waveform` and `WaveVStack` therefore avoid complex storage and arithmetic for
+Real waveforms and stacks therefore avoid complex storage and arithmetic for
 the common real-valued case. `ComplexWaveform.real` and `.imag` expose the two
 real channel waveforms.
 

waveforms-3.3.0/tests/test_core.py

@@ -0,0 +1,250 @@
+import pickle
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+import waveforms as wf
+import waveforms._waveform as core
+from waveforms._waveform import quantize_samples
+
+
+RATE = 2_400_000_000
+
+
+def _pulse():
+    return (
+        0.8 * wf.gaussian(20e-9) * wf.cos(2 * np.pi * 100e6)
+        + 0.15 * wf.gaussian(12e-9) * wf.sin(2 * np.pi * 180e6, 0.2)
+        + 0.05 * wf.square(6e-9)
+    )
+
+
+def _stack(count, spacing=40e-9):
+    pulse = 0.8 * wf.gaussian(20e-9) * wf.cos(2 * np.pi * 100e6)
+    stack = wf.WaveVStack([
+        pulse >> (index * spacing) for index in range(count)
+    ])
+    stack.start = -20e-9
+    stack.stop = count * spacing
+    stack.sample_rate = RATE
+    return stack
+
+
+def test_unified_type_hierarchy_and_removed_legacy_api():
+    real = wf.gaussian(20e-9)
+    complex_wave = real + 0.5j * real
+    real_stack = wf.WaveVStack([real])
+    complex_stack = wf.ComplexWaveVStack([complex_wave])
+
+    assert isinstance(real, wf.RealWaveform)
+    assert isinstance(real_stack, wf.RealWaveVStack)
+    assert isinstance(real_stack, wf.WaveVStack)
+    assert isinstance(complex_stack, wf.WaveVStack)
+    assert all(isinstance(value, wf.Waveform) for value in (
+        real, complex_wave, real_stack, complex_stack
+    ))
+    assert not any(name.startswith("native_") for name in dir(wf))
+    assert not any(name.startswith("Native") for name in dir(wf))
+    assert not hasattr(core, "PackedWaveform")
+    assert not hasattr(core, "PackedStack")
+
+
+def test_canonical_real_waveform_equality_and_hash():
+    a = wf.gaussian(12e-9)
+    b = wf.cos(2 * np.pi * 100e6)
+
+    assert a + b == b + a
+    assert hash(a + b) == hash(b + a)
+    assert a + a == 2 * a
+    assert a * a == a ** 2
+    assert (a + b).simplify().to_bytes() == (b + a).simplify().to_bytes()
+    assert wf.WaveVStack([a, b]) == wf.WaveVStack([b, a])
+
+
+def test_c_symbolic_frequency_filter():
+    envelope = wf.gaussian(20e-9)
+    low = envelope * wf.cos(2 * np.pi * 100e6)
+    high = 0.25 * envelope * wf.sin(2 * np.pi * 300e6)
+    baseband = 0.1 * envelope
+    signal = low + high + baseband
+    x = np.linspace(-20e-9, 20e-9, 4097)
+
+    assert np.allclose(
+        signal.filter(2 * np.pi * 200e6, 2 * np.pi * 400e6)(x),
+        high(x),
+    )
+    assert np.allclose(
+        signal.filter(0, 2 * np.pi * 200e6)(x),
+        (low + baseband)(x),
+    )
+
+
+def test_wave_block_roundtrip_pickle_and_numerics():
+    actual = _pulse()
+    actual.start = -20e-9
+    actual.stop = 20e-9
+    actual.sample_rate = RATE
+    actual.label = "pulse"
+    data = actual.to_bytes()
+    restored = wf.Waveform.from_bytes(data)
+    x = np.linspace(-20e-9, 20e-9, 200_000, endpoint=False)
+
+    assert data[:4] == b"WNF4"
+    assert actual.to_bytes() is data
+    assert restored.to_bytes() is data
+    assert restored == wf.Waveform.from_bytes(data)
+    assert wf.RealWaveform.from_bytes(data) == restored
+    assert np.array_equal(restored(x), actual(x))
+
+    unpickled = pickle.loads(pickle.dumps(actual, protocol=5))
+    assert unpickled == actual
+    assert unpickled.start == actual.start
+    assert unpickled.stop == actual.stop
+    assert unpickled.sample_rate == actual.sample_rate
+    assert unpickled.label == actual.label
+
+
+@pytest.mark.parametrize("dtype", [np.float64, np.int16, np.int32])
+def test_device_grid_sampling_and_output_buffer(dtype):
+    actual = _pulse()
+    actual.start = -20e-9
+    actual.stop = 20e-9
+    actual.sample_rate = RATE
+    result = actual.sample(dtype=dtype)
+    target = np.empty_like(result)
+    assert actual.sample(dtype=dtype, out=target) is target
+    assert np.array_equal(target, result)
+
+
+def test_complex_block_roundtrip_and_pickle():
+    pulse = _pulse()
+    complex_wave = pulse + 0.5j * (pulse >> 2e-9)
+    complex_wave.start = -20e-9
+    complex_wave.stop = 20e-9
+    complex_wave.sample_rate = RATE
+    complex_wave.label = "iq"
+    x = np.linspace(-20e-9, 20e-9, 8192, endpoint=False)
+    expected = pulse(x) + 0.5j * (pulse >> 2e-9)(x)
+
+    data = complex_wave.to_bytes()
+    restored = wf.Waveform.from_bytes(data)
+    assert data[:4] == b"CWF1"
+    assert isinstance(restored, wf.ComplexWaveform)
+    assert np.allclose(restored(x), expected, rtol=2e-15, atol=2e-15)
+    unpickled = pickle.loads(pickle.dumps(complex_wave, protocol=5))
+    assert np.allclose(unpickled(x), expected, rtol=2e-15, atol=2e-15)
+    assert unpickled.label == complex_wave.label
+
+
+def test_stack_sampling_roundtrip_shift_offset_and_pickle():
+    actual = _stack(100)
+    data = actual.to_bytes()
+    restored = wf.WaveVStack.from_bytes(data)
+    restored.start = actual.start
+    restored.stop = actual.stop
+    restored.sample_rate = actual.sample_rate
+
+    assert data[:4] == b"WNS4"
+    assert restored.to_bytes() is data
+    assert isinstance(wf.RealWaveVStack.from_bytes(data),
+                      wf.RealWaveVStack)
+    assert np.array_equal(restored.sample(), actual.sample())
+    assert np.array_equal(restored.sample(dtype=np.int16),
+                          actual.sample(dtype=np.int16))
+
+    transformed = (actual >> 5e-9) + 0.125
+    transformed_restored = wf.WaveVStack.from_bytes(transformed.to_bytes())
+    x = np.linspace(-20e-9, 4e-6, 10_000, endpoint=False)
+    assert np.allclose(transformed_restored(x), transformed(x),
+                       rtol=2e-15, atol=2e-15)
+
+    actual.label = "events"
+    unpickled = pickle.loads(pickle.dumps(actual, protocol=5))
+    assert unpickled == actual
+    assert unpickled.sample_rate == actual.sample_rate
+    assert unpickled.label == actual.label
+
+
+@pytest.mark.parametrize("dtype,bits", [
+    (np.float64, 0),
+    (np.int16, 16),
+    (np.int32, 32),
+])
+def test_stack_sample_plan_matches_direct_sampler(dtype, bits):
+    pulse = wf.gaussian(20e-9) * wf.cos(2 * np.pi * 100e6)
+    scales = (0.25, 0.5, 1.0)
+    actual = wf.WaveVStack([
+        scales[index % len(scales)] * pulse >> (index * 40e-9)
+        for index in range(75)
+    ])
+    actual.start = -20e-9
+    actual.stop = 75 * 40e-9
+    actual.sample_rate = RATE
+    actual.offset = 0.071
+
+    first = actual.sample(dtype=dtype)
+    cache_key, sample_plan = actual._sample_plan_cache
+    target = np.empty_like(first)
+    result = actual.sample(dtype=dtype, out=target)
+    direct = actual._core.sample(
+        cache_key[0], cache_key[1], cache_key[2], cache_key[3],
+        cache_key[4], actual.offset, bits, 1.0,
+    )
+
+    assert result is target
+    assert sample_plan.count == len(result)
+    assert sample_plan.group_count == 1
+    assert sample_plan.non_overlapping
+    assert np.array_equal(result, direct)
+    assert actual._sample_plan_cache[1] is sample_plan
+
+
+def test_overlapping_stack_quantization_and_empty_stack():
+    actual = _stack(50, spacing=10e-9)
+    for dtype, bits in ((np.int16, 16), (np.int32, 32)):
+        expected = quantize_samples(actual.sample(), bits)
+        assert np.array_equal(actual.sample(dtype=dtype), expected)
+
+    empty = wf.WaveVStack([])
+    empty.start = -1e-9
+    empty.stop = 1e-9
+    empty.sample_rate = RATE
+    assert empty.to_bytes() == b"WNS4\x02\x00\x00\x00" + b"\x00" * 8
+    assert not np.any(empty.sample())
+    assert not np.any(wf.WaveVStack.from_bytes(empty.to_bytes())(
+        np.linspace(-1e-9, 1e-9, 17)
+    ))
+
+
+def test_blocks_reject_malformed_layouts():
+    wave_data = bytearray(_pulse().to_bytes())
+    with pytest.raises(ValueError):
+        wf.Waveform.from_bytes(wave_data[:20])
+    wave_data[0] = 0
+    with pytest.raises(ValueError):
+        wf.Waveform.from_bytes(wave_data)
+
+    wave_data = bytearray(_pulse().to_bytes())
+    wave_data[24] = 255
+    with pytest.raises(ValueError):
+        wf.Waveform.from_bytes(wave_data)
+
+    stack_data = bytearray(_stack(2).to_bytes())
+    with pytest.raises(ValueError):
+        wf.WaveVStack.from_bytes(stack_data[:-1])
+    event_offset = len(stack_data) - 40
+    stack_data[event_offset:event_offset + 4] = (99).to_bytes(4, "little")
+    malformed = wf.WaveVStack.from_bytes(stack_data)
+    with pytest.raises(ValueError):
+        _ = malformed._core.event_count
+
+
+def test_format_is_language_neutral_and_uses_the_global_clock():
+    data = _pulse().to_bytes()
+    assert data[:4] == b"WNF4"
+    assert int.from_bytes(data[4:6], "little") == 2
+    assert wf.get_time_resolution() == 1 / 120_000_000_000
+    package_dir = Path(wf.__file__).resolve().parent
+    assert (package_dir / "_cwaveform.c").is_file()
+    assert (package_dir / "_cwaveform.h").is_file()

{waveforms-3.2.0 → waveforms-3.3.0}/tests/test_waveform.py

@@ -15,7 +15,8 @@ from waveforms._waveform import (
 
 
 PUBLIC_NAMES = {
-    "ComplexWaveform", "ComplexWaveVStack", "D", "Waveform", "WaveVStack",
+    "ComplexWaveform", "ComplexWaveVStack", "D", "RealWaveform",
+    "RealWaveVStack", "Waveform", "WaveVStack",
     "chirp", "const", "cos", "cosh",
     "coshPulse", "cosPulse", "cut", "drag", "drag_sin", "drag_sinx",
     "exp", "function",
@@ -51,19 +52,13 @@ def test_affine_algebra_matches_eager_materialization():
     right = -1.25 * (wf.cos(2.3, 0.4) << 0.35)
 
     actual_add = left + right
-    eager_add = wf.Waveform._from_core(
-        left._materialized_core().add(right._materialized_core())
-    )
     actual_mul = left * right
-    eager_mul = wf.Waveform._from_core(
-        left._materialized_core().mul(right._materialized_core())
-    )
 
     x = np.linspace(-3, 4, 8193)
-    assert actual_add.to_bytes() == eager_add.to_bytes()
-    assert actual_mul.to_bytes() == eager_mul.to_bytes()
-    assert np.array_equal(actual_add(x), eager_add(x))
-    assert np.array_equal(actual_mul(x), eager_mul(x))
+    assert np.allclose(actual_add(x), left(x) + right(x),
+                       rtol=2e-15, atol=2e-15)
+    assert np.allclose(actual_mul(x), left(x) * right(x),
+                       rtol=2e-15, atol=2e-15)
     assert wf.Waveform.from_bytes(actual_add.to_bytes()) == actual_add
     assert wf.Waveform.from_bytes(actual_mul.to_bytes()) == actual_mul
 
@@ -272,7 +267,7 @@ def test_wavevstack_template_sharing_operations_and_roundtrip():
     waves = [template >> (i * 80e-9) for i in range(1000)]
     stack = wf.WaveVStack(waves)
 
-    # One template plus three packed event arrays; substantially smaller than
+    # One template plus three contiguous event arrays; substantially smaller than
     # serializing 1000 complete shifted expression trees.
     assert len(stack.to_bytes()) < 32_000
     x = np.linspace(0, 80e-6, 16_000, endpoint=False)
@@ -410,30 +405,26 @@ def test_complex_interpolation_and_stack_roundtrip():
         wf.WaveVStack(waves)
 
 
-def test_packed_backend_rejects_complex_coefficients_and_scales():
+def test_real_backend_promotes_complex_coefficients_and_scales():
     wav = wf.gaussian(1.0)
     stack = wf.WaveVStack([wav, 2 * (wav >> 3)])
-    assert wav.to_bytes()[:4] == b"WFM3"
-    assert stack.to_bytes()[:4] == b"WVS3"
-    assert all(isinstance(scale, float)
-               for _, _, scale in stack._stack.events())
+    assert wav.to_bytes()[:4] == b"WNF4"
+    assert stack.to_bytes()[:4] == b"WNS4"
     assert stack(np.linspace(-1, 4, 101)).dtype == np.float64
 
-    with pytest.raises(TypeError, match="must be real"):
-        wav._core.scaled(1j)
-    with pytest.raises(TypeError, match="must be real"):
-        stack._stack.scaled(1j)
-    with pytest.raises(TypeError, match="positions must be real"):
+    assert isinstance(wav * 1j, wf.ComplexWaveform)
+    assert isinstance(stack * 1j, wf.ComplexWaveVStack)
+    with pytest.raises((TypeError, ValueError)):
         wav(np.array([0.0 + 0.0j]))
 
 
 def test_time_is_global_configuration_and_blocks_store_integer_ticks():
     assert wf.get_time_resolution() == 1 / 120_000_000_000
     wav = wf.square(4e-9) >> 11e-9
-    ticks = wav._core.get_bound_ticks()
-    assert ticks.dtype == np.dtype("<i8")
-    assert np.array_equal(ticks[:-1], [-240, 240])
-    assert wav._delay == 11e-9
+    data = wav.to_bytes()
+    assert data[:4] == b"WNF4"
+    assert wav.begin == 9e-9
+    assert wav.end == 13e-9
     with pytest.raises(RuntimeError):
         wf.set_time_resolution(1e-15)
 
@@ -441,7 +432,7 @@ def test_time_is_global_configuration_and_blocks_store_integer_ticks():
         "import waveforms as w; "
         "w.set_time_resolution(1e-15); "
         "x=w.square(4e-12); "
-        "print(w.get_time_resolution(), x._core.get_bound_ticks()[0])"
+        "print(w.get_time_resolution(), round(x.begin / 1e-15))"
     )
     result = subprocess.run([sys.executable, "-c", code], check=True,
                             capture_output=True, text=True)
@@ -576,14 +567,8 @@ def test_wavevstack_integer_grid_template_sampling_and_complex_iq():
     stack.start = -10e-9
     stack.stop = 110e-9
     actual = stack.sample(rate)
-    start_tick = time_to_tick(stack.start)
-    expected = np.full(len(actual), stack.offset)
-    for core, delay, scale in stack._stack.events():
-        delay_tick = time_to_tick(delay + stack.shift)
-        local_grid = sample_grid(
-            start_tick - delay_tick, len(actual), *step
-        )
-        expected += scale * core.evaluate(local_grid)
+    x = sample_grid(time_to_tick(stack.start), len(actual), *step)
+    expected = stack(x)
     assert np.allclose(actual, expected, rtol=2e-15, atol=2e-15)
 
     complex_stack = wf.ComplexWaveVStack(stack, -0.5 * stack)
@@ -595,12 +580,16 @@ def test_wavevstack_integer_grid_template_sampling_and_complex_iq():
     assert np.array_equal(q_data, quantize_samples(complex_samples.imag, 16))
 
 
-def test_single_packed_backend_has_no_waveform2_modules():
+def test_single_c_backend_has_no_waveform2_or_packed_core():
     package = Path(wf.__file__).parent
     python_source = (package / "waveform.py").read_text()
     cython_source = (package / "_waveform.pyx").read_text()
     assert "waveform2" not in python_source
     assert "_waveform2" not in cython_source
+    assert "PackedWaveform" not in python_source + cython_source
+    assert "PackedStack" not in python_source + cython_source
+    assert "WFM3" not in python_source + cython_source
+    assert "WVS3" not in python_source + cython_source
     assert not (package / "waveform2.py").exists()
     assert not (package / "_waveform2.pyx").exists()
 

{waveforms-3.2.0 → waveforms-3.3.0}/waveforms/__init__.py

@@ -5,11 +5,10 @@ from .waveform import (
     ComplexWaveform,
     ComplexWaveVStack,
     D,
+    RealWaveform,
+    RealWaveVStack,
     Waveform,
     WaveVStack,
-    NativeWaveform,
-    NativeWaveVStack,
-    NativeComplexWaveform,
     chirp,
     const,
     cos,
@@ -44,19 +43,11 @@ from .waveform import (
     t,
     wave_eval,
     zero,
-    native_zero,
-    native_one,
-    native_const,
-    native_gaussian,
-    native_cos,
-    native_sin,
-    native_square,
-    native_format_description,
 )
 
 __all__ = [
-    "ComplexWaveform", "ComplexWaveVStack", "D", "Waveform", "WaveVStack",
-    "NativeWaveform", "NativeWaveVStack", "NativeComplexWaveform",
+    "ComplexWaveform", "ComplexWaveVStack", "D", "RealWaveform",
+    "RealWaveVStack", "Waveform", "WaveVStack",
     "chirp", "const", "cos", "cosh",
     "coshPulse", "cosPulse", "cut", "drag", "drag_sin", "drag_sinx",
     "e", "exp", "function",
@@ -65,6 +56,4 @@ __all__ = [
     "registerBaseFunc", "registerDerivative", "samplingPoints",
     "set_time_resolution", "sign", "sin", "sinc", "sinh", "square",
     "step", "t", "wave_eval", "zero", "__version__",
-    "native_zero", "native_one", "native_const", "native_gaussian",
-    "native_cos", "native_sin", "native_square", "native_format_description",
 ]