waveforms 2.2.3__tar.gz → 3.0.0__tar.gz

{waveforms-2.2.3 → waveforms-3.0.0}/MANIFEST.in

@@ -1,4 +1,5 @@
 include src/*.h
 include waveforms/_waveform.pyx
+include waveforms/_waveform.pyi
 include waveforms/Waveform.g4
-include MANIFEST.in
+include MANIFEST.in

{waveforms-2.2.3/waveforms.egg-info → waveforms-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: waveforms
-Version: 2.2.3
+Version: 3.0.0
 Summary: Edit waveforms used in experiment
 Author-email: feihoo87 <feihoo87@gmail.com>
 Maintainer-email: feihoo87 <feihoo87@gmail.com>
@@ -21,6 +21,8 @@ Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -96,6 +98,28 @@ plt.plot(t, y_wav(t))
 plt.show()
 ```
 
+### Packed 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.
+
+```python
+import waveforms as wf
+
+# Optional; call this once, before constructing or loading waveform objects.
+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)
+```
+
+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.
+
 ## Reporting Issues
 Please report all issues [on github](https://github.com/feihoo87/waveforms/issues).
 

{waveforms-2.2.3 → waveforms-3.0.0}/README.md

@@ -54,6 +54,28 @@ plt.plot(t, y_wav(t))
 plt.show()
 ```
 
+### Packed 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.
+
+```python
+import waveforms as wf
+
+# Optional; call this once, before constructing or loading waveform objects.
+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)
+```
+
+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.
+
 ## Reporting Issues
 Please report all issues [on github](https://github.com/feihoo87/waveforms/issues).
 

{waveforms-2.2.3 → waveforms-3.0.0}/pyproject.toml

@@ -27,6 +27,8 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
 ]
 requires-python = ">= 3.10"
 dependencies = [
@@ -69,7 +71,7 @@ license-files = ["LICENSE"]
 include-package-data = true
 
 [tool.setuptools.package-data]
-waveforms = ["WaveformLexer.py", "WaveformParser.py", "WaveformListener.py"]
+waveforms = ["WaveformLexer.py", "WaveformParser.py", "WaveformListener.py", "*.pyi"]
 
 [tool.setuptools.dynamic]
 version = {attr = "waveforms.version.__version__"}

waveforms-3.0.0/tests/test_waveform.py

@@ -0,0 +1,254 @@
+import pickle
+import subprocess
+import sys
+from pathlib import Path
+
+import numpy as np
+import pytest
+import scipy.special as special
+from scipy.signal import butter, lfilter, lfiltic, tf2sos
+
+import waveforms as wf
+
+
+PUBLIC_NAMES = {
+    "D", "Waveform", "WaveVStack", "chirp", "const", "cos", "cosh",
+    "coshPulse", "cosPulse", "cut", "drag", "exp", "function",
+    "gaussian", "general_cosine", "get_time_resolution", "hanning", "interp", "mixing",
+    "mollifier", "one", "poly", "registerBaseFunc", "registerDerivative",
+    "samplingPoints", "set_time_resolution", "sign", "sin", "sinc", "sinh", "square", "step",
+    "t", "wave_eval", "zero",
+}
+
+
+def test_public_api_and_basic_sampling():
+    assert PUBLIC_NAMES <= set(dir(wf))
+    x = np.linspace(-2.0, 2.0, 1001)
+    assert np.allclose(wf.cos(1.3)(x), np.cos(1.3 * x))
+    assert np.allclose(wf.sin(0.7)(x), np.sin(0.7 * x))
+    assert np.allclose(wf.poly([1, -0.5, 0.25])(x),
+                       1 - 0.5 * x + 0.25 * x**2)
+
+
+def test_binary_roundtrip_is_zero_copy_for_bytes_input():
+    wav = (wf.gaussian(0.8) >> 1.2) * wf.cos(2.3) + 0.25
+    data = wav.to_bytes()
+    restored = wf.Waveform.from_bytes(data)
+    assert restored._core.to_bytes() is data
+    assert restored == wav
+    assert pickle.loads(pickle.dumps(wav)) == wav
+    assert wf.one() >> 5 == wf.one()
+    assert (wf.const(2.5) << 7).to_bytes() == wf.const(2.5).to_bytes()
+
+
+def test_operations_simplify_derivative_and_clipping():
+    x = np.linspace(-1.9, 1.9, 4097)
+    wav = wf.cos(1) * wf.sin(2) * wf.cos(3, 4)
+    expected = np.cos(x) * np.sin(2 * x) * np.cos(3 * x + 4)
+    assert np.allclose(wav(x), expected)
+    assert np.allclose(wav.simplify()(x), expected)
+
+    width = 4.0
+    std_sq2 = width / 3.3302184446307908
+    order = 6
+    expected_d = ((-1)**order / std_sq2**order
+                  * special.eval_hermite(order, x / std_sq2)
+                  * np.exp(-(x / std_sq2)**2))
+    assert np.allclose(wf.gaussian(width, d=order)(x), expected_d)
+
+    clipped = 2 * wf.cos(2.1) + 0.3 * wf.sin(0.7)
+    clipped.min = -0.4
+    clipped.max = 0.6
+    assert np.allclose(clipped(x), np.clip(2 * np.cos(2.1 * x)
+                                          + 0.3 * np.sin(0.7 * x),
+                                          -0.4, 0.6))
+
+    width = 1.3
+    shift = 0.7
+    frequency = 2.1
+    phase = 0.4
+    std_sq2 = width / 3.3302184446307908
+    base = (wf.gaussian(width) >> shift) * wf.cos(frequency, phase)
+    inside = (x >= -0.75 * width + shift) & (x < 0.75 * width + shift)
+    for order in range(4):
+        expected = np.zeros_like(x)
+        z = (x[inside] - shift) / std_sq2
+        for gaussian_order in range(order + 1):
+            carrier_order = order - gaussian_order
+            gaussian_part = (
+                (-1) ** gaussian_order / std_sq2 ** gaussian_order
+                * special.eval_hermite(gaussian_order, z) * np.exp(-(z**2))
+            )
+            carrier_part = frequency ** carrier_order * np.cos(
+                frequency * x[inside] + phase + carrier_order * np.pi / 2
+            )
+            expected[inside] += (
+                special.comb(order, gaussian_order, exact=True)
+                * gaussian_part * carrier_part
+            )
+        assert np.allclose(wf.D(base, order)(x), expected,
+                           atol=2e-10, rtol=2e-10)
+
+
+def test_metadata_pickle_and_removed_experimental_serializers():
+    wav = (wf.gaussian(10) >> 5) + (wf.gaussian(10) >> 50)
+    wav *= wf.cos(200)
+    wav.start = -10
+    wav.stop = 70
+    wav.sample_rate = 20
+    wav.label = "pulse"
+
+    restored = pickle.loads(pickle.dumps(wav))
+    assert restored == wav
+    assert restored.start == wav.start
+    assert restored.stop == wav.stop
+    assert restored.sample_rate == wav.sample_rate
+    assert restored.label == wav.label
+    for name in ("tolist", "fromlist", "totree", "fromtree", "_as_v1"):
+        assert not hasattr(wav, name)
+    assert wav.begin == -2.5
+    assert wav.end == 57.5
+
+
+def test_sampling_points_chirps_and_mixing():
+    x = np.linspace(0, 2, 2048, endpoint=False)
+    points = np.sin(np.linspace(0, 3, 65))
+    sampled = wf.samplingPoints(0, 2, points)
+    assert np.allclose(sampled(x), np.interp(x, np.linspace(0, 2, 65), points))
+
+    for kind in ("linear", "exponential", "hyperbolic"):
+        wav = wf.chirp(1, 2, 2, 0.3, kind)
+        if kind == "linear":
+            phase = 0.3 + 2 * np.pi * ((2 - 1) / 4 * x**2 + x)
+        elif kind == "exponential":
+            alpha = np.log(2) / 2
+            phase = 0.3 + 2 * np.pi * (np.exp(alpha * x) - 1) / alpha
+        else:
+            k = (1 - 2) / (2 * 2)
+            phase = 0.3 + 2 * np.pi / k * np.log(1 + k * x)
+        assert np.allclose(wav(x), np.sin(phase))
+
+    i, q = wf.mixing(wf.gaussian(0.5), phase=0.2, freq=1.3,
+                     DRAGScaling=0.01)
+    assert np.all(np.isfinite(i(x)))
+    assert np.all(np.isfinite(q(x)))
+
+
+def test_filters_and_chunked_sampling():
+    sample_rate = 1000
+    b, a = butter(3, 4.0, "lowpass", fs=sample_rate)
+    zi = lfiltic(b, a, [0])
+    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]
+    assert np.allclose(wav.sample(), expected)
+    assert np.allclose(np.concatenate(list(wav.sample(chunk_size=137))), expected)
+
+
+def test_wavevstack_template_sharing_operations_and_roundtrip():
+    template = wf.gaussian(20e-9) * wf.cos(2 * np.pi * 5e9)
+    waves = [template >> (i * 80e-9) for i in range(1000)]
+    stack = wf.WaveVStack(waves)
+
+    # One template plus three packed 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)
+    assert np.allclose(stack(x), stack.simplify()(x))
+
+    shifted = (stack + 2.0) >> 1e-6
+    shifted = shifted * 0.25 + wf.sin(2 * np.pi * 1e6)
+    assert np.allclose(shifted(x), shifted.simplify()(x))
+
+    materialized = wf.WaveVStack.from_bytes(shifted.to_bytes())
+    assert np.allclose(materialized(x), shifted(x))
+
+    restored = wf.WaveVStack.from_bytes(stack.to_bytes())
+    assert restored == stack
+    assert pickle.loads(pickle.dumps(stack)) == stack
+
+
+def test_notebook_constructors_and_wave_eval():
+    x = np.linspace(-20, 60, 4001)
+    linear_step = np.where(x < -1, 0, np.where(x < 1, 0.5 + x / 2, 1))
+    cosine_step = np.where(
+        x < -1, 0, np.where(x < 1, 0.5 + 0.5 * np.sin(np.pi * x / 2), 1)
+    )
+    erf_step = np.where(
+        x < -2, 0, np.where(x < 2, 0.5 + 0.5 * special.erf(x / 0.4), 1)
+    )
+    assert np.allclose(wf.step(2, "linear")(x), linear_step)
+    assert np.allclose(wf.step(2, "cos")(x), cosine_step)
+    assert np.allclose(wf.step(2, "erf")(x), erf_step)
+
+    assert np.allclose(wf.exp(0.03 + 0.2j)(x), np.exp((0.03 + 0.2j) * x))
+    inside = np.array([-2.0, -1.0, 0.0, 1.5, 2.999])
+    assert np.allclose(wf.interp([-2, 0, 3], [1, -1, 2])(inside),
+                       np.interp(inside, [-2, 0, 3], [1, -1, 2]))
+
+    for wav in (wf.square(8, 2), wf.gaussian(8, 3), wf.cosPulse(8, 2),
+                wf.coshPulse(8, 2, 3), wf.mollifier(8, 2), wf.sinc(3)):
+        with np.errstate(divide="ignore", invalid="ignore"):
+            values = wav(x)
+        assert np.all(np.isfinite(values))
+
+    expression = ("(gaussian(12) >> 3) * cos(16.2, 1.63) + "
+                  "0.5*(gaussian(12) >> 35) * cos(16.2, 2)")
+    actual = wf.wave_eval(expression)
+    expected = wf.gaussian(12) >> 3
+    expected = expected * wf.cos(16.2, 1.63)
+    expected += 0.5 * (wf.gaussian(12) >> 35) * wf.cos(16.2, 2)
+    assert isinstance(actual, wf.Waveform)
+    assert np.allclose(actual(x), expected(x))
+
+
+def test_time_is_global_configuration_and_blocks_store_integer_ticks():
+    assert wf.get_time_resolution() == 1e-12
+    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], [-2_000, 2_000])
+    assert wav._delay == 11e-9
+    with pytest.raises(RuntimeError):
+        wf.set_time_resolution(1e-15)
+
+    code = (
+        "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])"
+    )
+    result = subprocess.run([sys.executable, "-c", code], check=True,
+                            capture_output=True, text=True)
+    assert result.stdout.strip() == "1e-15 -2000"
+
+
+def test_single_packed_backend_has_no_waveform2_modules():
+    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 not (package / "waveform2.py").exists()
+    assert not (package / "_waveform2.pyx").exists()
+
+    code = (
+        "import sys; from waveforms import gaussian; gaussian(1); "
+        "print('waveforms.waveform2' in sys.modules, "
+        "'waveforms._waveform2' in sys.modules)"
+    )
+    result = subprocess.run([sys.executable, "-c", code], check=True,
+                            capture_output=True, text=True)
+    assert result.stdout.strip() == "False False"
+
+
+def test_custom_functions_are_explicitly_unsupported():
+    with pytest.raises(NotImplementedError):
+        wf.function(lambda x: x)
+    with pytest.raises(NotImplementedError):
+        wf.registerBaseFunc(lambda x: x)

waveforms-3.0.0/tests/test_wavevstack.py

@@ -0,0 +1,61 @@
+import pickle
+
+import numpy as np
+from scipy.signal import butter, lfilter, lfiltic, tf2sos
+
+from waveforms import WaveVStack, cos, gaussian, pi, poly, sin, step, zero
+
+
+def _waves():
+    return [cos(1), sin(2), gaussian(3),
+            poly([1, -1 / 2, 1 / 6, -1 / 12])]
+
+
+def test_wavevstack_sampling_algebra_and_shifts():
+    x = np.linspace(-10, 10, 1001)
+    waves = _waves()
+    expected = zero()
+    for wav in waves:
+        expected += wav
+    stack = WaveVStack(waves)
+
+    assert stack.simplify() == expected
+    assert np.allclose(stack(x), expected(x))
+    assert np.allclose((stack + sin(2))(x), (expected + sin(2))(x))
+    assert np.allclose((stack - sin(2))(x), (expected - sin(2))(x))
+    assert np.allclose((stack * sin(2) + 3)(x),
+                       (expected * sin(2) + 3)(x))
+    assert np.allclose((stack / 2)(x), (expected / 2)(x))
+    assert np.allclose((stack >> 0.6)(x), (expected >> 0.6)(x))
+    assert np.allclose((stack << 1.4)(x), (expected << 1.4)(x))
+
+
+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])
+    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]
+
+    assert np.allclose(stack.sample(), expected, atol=1e-6)
+    chunks = np.concatenate(list(stack.sample(chunk_size=137)))
+    assert np.allclose(chunks, expected, atol=1e-6)
+
+
+def test_wavevstack_binary_template_sharing_and_pickle():
+    template = gaussian(20e-9) * cos(2 * pi * 5e9)
+    stack = WaveVStack([template >> (index * 80e-9)
+                        for index in range(10_000)])
+    assert len(stack.to_bytes()) < 300_000
+
+    restored = WaveVStack.from_bytes(stack.to_bytes())
+    assert restored == stack
+    assert pickle.loads(pickle.dumps(stack)) == stack

waveforms-3.0.0/waveforms/__init__.py

@@ -0,0 +1,50 @@
+from numpy import e, pi
+
+from .version import __version__
+from .waveform import (
+    D,
+    Waveform,
+    WaveVStack,
+    chirp,
+    const,
+    cos,
+    cosh,
+    coshPulse,
+    cosPulse,
+    cut,
+    drag,
+    exp,
+    function,
+    gaussian,
+    general_cosine,
+    get_time_resolution,
+    hanning,
+    interp,
+    mixing,
+    mollifier,
+    one,
+    poly,
+    registerBaseFunc,
+    registerDerivative,
+    samplingPoints,
+    set_time_resolution,
+    sign,
+    sin,
+    sinc,
+    sinh,
+    square,
+    step,
+    t,
+    wave_eval,
+    zero,
+)
+
+__all__ = [
+    "D", "Waveform", "WaveVStack", "chirp", "const", "cos", "cosh",
+    "coshPulse", "cosPulse", "cut", "drag", "e", "exp", "function",
+    "gaussian", "general_cosine", "get_time_resolution", "hanning",
+    "interp", "mixing", "mollifier", "one", "pi", "poly",
+    "registerBaseFunc", "registerDerivative", "samplingPoints",
+    "set_time_resolution", "sign", "sin", "sinc", "sinh", "square",
+    "step", "t", "wave_eval", "zero", "__version__",
+]

waveforms-3.0.0/waveforms/_waveform.pyi

@@ -0,0 +1,73 @@
+from typing import Iterable
+
+import numpy as np
+
+NDIGITS: int
+LINEAR: int
+GAUSSIAN: int
+ERF: int
+COS: int
+SINC: int
+EXP: int
+INTERP: int
+LINEARCHIRP: int
+EXPONENTIALCHIRP: int
+HYPERBOLICCHIRP: int
+COSH: int
+SINH: int
+DRAG: int
+MOLLIFIER: int
+D_GAUSSIAN: int
+
+
+class PackedWaveform:
+    def __init__(self, data: bytes | bytearray | memoryview = ...) -> None: ...
+    @classmethod
+    def from_bytes(cls, data: bytes | bytearray | memoryview) -> PackedWaveform: ...
+    def to_bytes(self) -> bytes: ...
+    def get_bounds(self) -> np.ndarray: ...
+    def get_bound_ticks(self) -> np.ndarray: ...
+    def shifted(self, time: float) -> PackedWaveform: ...
+    def scaled(self, value: int | float | complex) -> PackedWaveform: ...
+    def add(self, other: PackedWaveform) -> PackedWaveform: ...
+    def mul(self, other: PackedWaveform) -> PackedWaveform: ...
+    def power(self, n: int) -> PackedWaveform: ...
+    def simplify(self, eps: float = ...) -> PackedWaveform: ...
+    def filtered(self, low: float = ..., high: float = ...,
+                 eps: float = ...) -> PackedWaveform: ...
+    def derivative(self, order: int = ...) -> PackedWaveform: ...
+    def evaluate(self, x: np.ndarray, lower: float = ...,
+                 upper: float = ...) -> np.ndarray: ...
+    def evaluate_shifted(self, x: np.ndarray, delay: float,
+                         lower: float = ..., upper: float = ...) -> np.ndarray: ...
+    def parts(self, x: np.ndarray, lower: float = ...,
+              upper: float = ...) -> tuple[list, type]: ...
+    def parts_shifted(self, x: np.ndarray, delay: float,
+                      lower: float = ..., upper: float = ...) -> tuple[list, type]: ...
+
+
+class PackedStack:
+    @classmethod
+    def from_bytes(cls, data: bytes | bytearray | memoryview) -> PackedStack: ...
+    @classmethod
+    def from_events(cls, events: Iterable[tuple[PackedWaveform, float,
+                                                complex]]) -> PackedStack: ...
+    def to_bytes(self) -> bytes: ...
+    def events(self) -> tuple[tuple[PackedWaveform, float, complex], ...]: ...
+    def evaluate(self, x: np.ndarray, offset: complex = ...,
+                 shift: float = ...) -> np.ndarray: ...
+    def simplified(self, shift: float = ..., offset: complex = ...,
+                   eps: float = ...) -> PackedWaveform: ...
+    def combined(self, other: PackedStack) -> PackedStack: ...
+    def scaled(self, value: complex) -> PackedStack: ...
+
+
+def constant(value: int | float | complex) -> PackedWaveform: ...
+def basic(opcode: int, args: tuple = ..., shift: float = ...) -> PackedWaveform: ...
+def piecewise(bounds: tuple, expressions: tuple) -> PackedWaveform: ...
+def sum_cores(cores: Iterable[PackedWaveform]) -> PackedWaveform: ...
+def set_time_resolution(value: float) -> None: ...
+def get_time_resolution() -> float: ...
+def quantize_time(value: float) -> float: ...
+def registerBaseFunc(*args, **kwargs): ...
+def registerDerivative(*args, **kwargs): ...