waveforms 3.1.0__tar.gz → 3.3.0__tar.gz

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

@@ -1,4 +1,6 @@
-include src/*.h
+include waveforms/_cwaveform.h
+include waveforms/_cwaveform.c
+include waveforms/_cwaveform.md
 include waveforms/_waveform.pyx
 include waveforms/_waveform.pyi
 include waveforms/Waveform.g4

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: waveforms
-Version: 3.1.0
+Version: 3.3.0
 Summary: Edit waveforms used in experiment
 Author-email: feihoo87 <feihoo87@gmail.com>
 Maintainer-email: feihoo87 <feihoo87@gmail.com>
@@ -98,27 +98,60 @@ 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
 
-# Optional; call this once, before constructing or loading waveform objects.
-wf.set_time_resolution(1e-12)
+# The default tick is already the period of 120 GHz (1 / 120e9 seconds).
+# To use another global tick, override it before constructing/loading waveforms:
+# wf.set_time_resolution(1e-12)
 
 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)
+```
+
+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
+quantized directly to signed DAC buffers:
+
+```python
+pulse.start = 0
+pulse.stop = 100e-9
+dac16 = pulse.sample(2_400_000_000, dtype=np.int16, full_scale=1.0)
+```
+
+The low-level cores store and evaluate real-valued signals only. Complex signals
+are represented in Python as independent real and imaginary channels:
+
+```python
+z = (1 + 0.25j) * wf.gaussian(12e-9)
+assert isinstance(z, wf.ComplexWaveform)
+
+stack = wf.ComplexWaveVStack([z, z >> 20e-9])
+samples = stack(t)  # complex NumPy array
 ```
 
-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.
+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.
 
 ## Reporting Issues
 Please report all issues [on github](https://github.com/feihoo87/waveforms/issues).

waveforms-3.3.0/README.md

@@ -0,0 +1,117 @@
+# waveforms
+[![View build status](https://github.com/feihoo87/waveforms/actions/workflows/workflow.yml/badge.svg)](https://github.com/feihoo87/waveforms/)
+[![Coverage Status](https://coveralls.io/repos/github/feihoo87/waveforms/badge.svg?branch=master)](https://coveralls.io/github/feihoo87/waveforms?branch=master)
+[![PyPI version](https://badge.fury.io/py/waveforms.svg)](https://pypi.org/project/waveforms/)
+
+Form waveforms used in experiment.
+
+## Installation
+We encourage installing waveforms via the pip tool (a python package manager):
+```bash
+python -m pip install waveforms
+```
+
+To install from the latest source, you need to clone the GitHub repository on your machine.
+```bash
+git clone https://github.com/feihoo87/waveforms.git
+```
+
+Then dependencies and `waveforms` can be installed in this way:
+```bash
+cd waveforms
+python -m pip install numpy
+python -m pip install -e .
+```
+
+## Usage
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+
+from waveforms import *
+
+pulse = cosPulse(20e-9)
+
+x_wav = zero()
+y_wav = zero()
+
+I, Q = mixing(0.5*pulse, freq=-20e6, DRAGScaling=0.2)
+x_wav += I
+y_wav += Q
+
+I, Q = mixing(pulse >> 1e-6, freq=-20e6, phase=np.pi/2, DRAGScaling=0.2)
+x_wav += I
+y_wav += Q
+
+I, Q = mixing((0.5 * pulse) >> 2e-6, freq=-20e6, DRAGScaling=0.2)
+x_wav += I
+y_wav += Q
+
+
+t = np.linspace(-1e-6, 9e-6, 10001)
+plt.plot(t, x_wav(t))
+plt.plot(t, y_wav(t))
+plt.show()
+```
+
+### Unified binary representation
+
+`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
+
+# The default tick is already the period of 120 GHz (1 / 120e9 seconds).
+# To use another global tick, override it before constructing/loading waveforms:
+# wf.set_time_resolution(1e-12)
+
+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)
+```
+
+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
+quantized directly to signed DAC buffers:
+
+```python
+pulse.start = 0
+pulse.stop = 100e-9
+dac16 = pulse.sample(2_400_000_000, dtype=np.int16, full_scale=1.0)
+```
+
+The low-level cores store and evaluate real-valued signals only. Complex signals
+are represented in Python as independent real and imaginary channels:
+
+```python
+z = (1 + 0.25j) * wf.gaussian(12e-9)
+assert isinstance(z, wf.ComplexWaveform)
+
+stack = wf.ComplexWaveVStack([z, z >> 20e-9])
+samples = stack(t)  # complex NumPy array
+```
+
+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.
+
+## Reporting Issues
+Please report all issues [on github](https://github.com/feihoo87/waveforms/issues).
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)

{waveforms-3.1.0 → waveforms-3.3.0}/pyproject.toml

@@ -71,7 +71,15 @@ license-files = ["LICENSE"]
 include-package-data = true
 
 [tool.setuptools.package-data]
-waveforms = ["WaveformLexer.py", "WaveformParser.py", "WaveformListener.py", "*.pyi"]
+waveforms = [
+    "WaveformLexer.py",
+    "WaveformParser.py",
+    "WaveformListener.py",
+    "*.pyi",
+    "_cwaveform.h",
+    "_cwaveform.c",
+    "_cwaveform.md",
+]
 
 [tool.setuptools.dynamic]
 version = {attr = "waveforms.version.__version__"}

{waveforms-3.1.0 → waveforms-3.3.0}/setup.py

@@ -1,4 +1,5 @@
 import os
+import sys
 
 from Cython.Build import cythonize
 from setuptools import Extension, find_packages, setup
@@ -35,9 +36,19 @@ def get_extensions():
     for dirpath, dirnames, filenames in os.walk('waveforms'):
         for filename in filenames:
             if filename.endswith('.pyx'):
+                sources = [os.path.join(dirpath, filename)]
+                include_dirs = []
+                extra_link_args = []
+                if filename == '_waveform.pyx':
+                    sources.append(os.path.join(
+                        'waveforms', '_cwaveform.c'))
+                    include_dirs.append('waveforms')
+                    if sys.platform == 'darwin':
+                        extra_link_args.extend(['-framework', 'Accelerate'])
                 extensions.append(
-                    Extension(module_name(dirpath, filename),
-                              [os.path.join(dirpath, filename)]))
+                    Extension(module_name(dirpath, filename), sources,
+                              include_dirs=include_dirs,
+                              extra_link_args=extra_link_args))
 
     return extensions
 

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()