polars-waveform 0.1.0__tar.gz

polars_waveform-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.13"]
+        polars: ["polars==1.40.0", "polars"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: install
+        run: python -m pip install ".[test]" "${{ matrix.polars }}"
+      - name: pytest
+        run: python -m pytest -q tests
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uvx ruff check .
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: python -m pip install build && python -m build --outdir dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+  pypi:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [test, lint, build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/polars-waveform
+    permissions:
+      id-token: write # trusted publishing, no API token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

polars_waveform-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+uv.lock

polars_waveform-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 polars-waveform contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

polars_waveform-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: polars-waveform
+Version: 0.1.0
+Summary: Waveforms and curve families on Polars, with circuit-style measurements (bandwidth, cross, rise time, ...)
+Project-URL: Repository, https://github.com/henjo/polars-waveform
+Project-URL: Issues, https://github.com/henjo/polars-waveform/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: eda,measurement,ocean,polars,simulation,waveform
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: polars>=1.40
+Provides-Extra: altair
+Requires-Dist: altair>=5.4; extra == 'altair'
+Provides-Extra: matplotlib
+Requires-Dist: matplotlib; extra == 'matplotlib'
+Requires-Dist: numpy; extra == 'matplotlib'
+Provides-Extra: numpy
+Requires-Dist: numpy; extra == 'numpy'
+Provides-Extra: pandas
+Requires-Dist: numpy; extra == 'pandas'
+Requires-Dist: pandas>=2.2; extra == 'pandas'
+Provides-Extra: test
+Requires-Dist: matplotlib; extra == 'test'
+Requires-Dist: numpy; extra == 'test'
+Requires-Dist: pandas>=2.2; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: sympy; extra == 'test'
+Description-Content-Type: text/markdown
+
+# polars-waveform
+
+Waveforms and curve families on [Polars](https://pola.rs), with circuit-style measurements:
+bandwidth, crossings, rise time, phase margin, ... Works on any Polars data: simulation results
+(through [polars-psf](https://github.com/henjo/polars-psf) for Cadence® Spectre® PSF files), lab measurements in Parquet,
+or a DataFrame you built yourself. Pure Python; depends only on `polars`.
+
+polars-waveform is an independent community project, not affiliated with or endorsed by the Polars
+project or by Cadence Design Systems, Inc.
+
+```sh
+pip install polars-waveform          # or: uv add polars-waveform
+```
+
+## Quick start
+
+```python
+import polars as pl
+import polars_waveform as pw
+
+df = pl.DataFrame({"t": [0.0, 1.0, 2.0, 3.0], "v": [0.0, 0.4, 0.9, 1.0]})
+w = pw.Waveform(df, "v")             # the last index column (t) is the sweep
+
+w.ymax(), w.cross(0.5), w.rise_time(), w.value(1.5)
+w.deriv(), w.clip(0.5, 2.5), w * 2 - 1
+```
+
+## Families: one curve per operating point
+
+Index columns besides the sweep are groups. A Waveform then holds a family of curves (devices,
+temperatures, Monte Carlo runs), and every measurement returns a table with one row per curve:
+
+```python
+lf = pl.scan_parquet("lab.parquet")                          # lazy: read on first use
+gain = pw.Waveform(lf.select("dut", "temp", "freq", "gain"), "gain", index=["dut", "temp", "freq"])
+
+gain.bandwidth()                     # dut | temp | bandwidth
+gain.leaf(dut="A1", temp=25.0)       # one curve (a single curve gives plain numbers)
+gain - gain.mean()                   # per-curve results broadcast back over the curves
+```
+
+Those tables are ordinary Polars DataFrames: sort, filter, join with other measurements, and
+`write_csv` / `write_excel`.
+
+Families can also be reshaped, all lazily:
+
+```python
+gain.reduce("min", over="temp")      # worst case over temperature: a family over dut x freq
+gain.ymax(axis="temp")               # the same with an axis argument (axis=-1, the sweep, is per curve)
+gain.reorder(["dut", "freq", "temp"])  # curves over temperature, one per dut and frequency
+for dut, g in gain.along("dut"):     # iterate over one group column
+    print(dut, g.bandwidth())
+gain[-1]                             # last sample of every curve (a number for a single curve)
+gain[10:20]                          # a slice of every curve
+```
+
+## From numpy arrays
+
+`Waveform.from_arrays` takes one array per sweep axis and an n-dimensional `y` (the last axis is
+the sweep, the others become groups), or ragged object arrays; `to_arrays()` converts back:
+
+```python
+w = pw.Waveform.from_arrays([temps, freqs], gain_2d, xlabels=["temp", "freq"], ylabel="gain")
+xs, y = w.to_arrays()
+```
+
+numpy functions keep waveforms as waveforms: `np.abs(w)`, `np.log10(w)`, `array + w`.
+
+## Nested channels
+
+Measurement tables often keep one row per operating point and store each *channel*, a curve
+with its own sweep, in a nested column:
+
+```
+lbw | vdd | idd | ... | pn: {offset: [..], psd: [..]} | spurs: {freq: [..], level: [..]}
+```
+
+`from_nested` turns a channel into a family, one curve per row, without flattening the table.
+Only the group columns and that channel are read:
+
+```python
+pn = pw.from_nested(pl.scan_parquet("pll.parquet"), "pn", x="offset", y="psd",
+                    groups=["lbw", "vdd"], units={"offset": "Hz", "psd": "dBc/Hz"})
+
+pn.value(1e6)                                    # phase noise at 1 MHz offset, per lbw x vdd
+(10 ** (pn / 10)).integ(1e4, 1e7)                # integrated phase noise, per lbw x vdd
+```
+
+Both nested shapes work: a struct of lists (`{x: [..], y: [..]}`) and a list of structs.
+
+## Plotting
+
+```sh
+pip install "polars-waveform[matplotlib]"    # or [altair] for interactive charts
+```
+
+```python
+w.plot()                         # matplotlib: one line per curve, labelled with its group values
+w.semilogx(), w.loglog(), w.stem()
+h.bode()                         # magnitude and phase of a complex response
+w.plot(backend="altair")         # interactive chart (notebooks); pw.set_plot_backend("altair")
+pw.compression_plot(gain_db)     # response, extrapolated line and the compression point
+```
+
+## Measurements
+
+The semantics follow OCEAN, and the OCEAN and pycircuit names are aliases (`pw.dB20`,
+`pw.unityGainFreq`, `pw.riseTime`, `pw.IIP3`, ...):
+
+| | |
+|---|---|
+| values | `value(x)`, `ymax()`, `ymin()`, `xmax()` (x at the largest y), `xmin()`, `average()`/`mean()`, `rms()`, `stddev()` |
+| crossings | `cross(threshold, edge=1, type="either")` (edges from 1, negative from the end), `delay(other, ...)`, `frequency()`, `period()` |
+| transient | `rise_time()`, `fall_time()`, `slew_rate()`, `overshoot()`, `settling_time()` |
+| frequency | `bandwidth(db, "low"/"high"/"band")`, `unity_gain_frequency()`, `phase_margin()`, `gain_margin()` |
+| shape | `deriv()`, `integ(xfrom, xto)`, `iinteg()`, `clip(xfrom, xto)`, `dft()`, `leaf(**groups)` |
+| families | `reduce(how, over)`, `ymax(axis=...)` and friends, `reorder()`, `swapaxes()`, `along()`, `dimension_first()`, `leaf()`, `w[i]`, `w[a:b]` |
+| math | `+ - * /`, `**`, `10 ** w`, `abs()`/`mag()`, `db10()`, `db20()`, `phase()`, `real()`, `imag()`, `conj()`, `log10()`, `exp()`, `sqrt()` |
+| RF | `pw.im2`, `pw.im3`, `pw.iip2`, `pw.iip3`, `pw.compression_point` |
+
+The elementwise functions (`pw.db20`, `pw.phase`, `pw.mag`, ...) also take plain numbers and
+numpy arrays. Complex data is a `Struct{re, im}` column; arithmetic and `db20()`/`phase()` handle it, and
+`pl.col("h").cx.db20()` (registered by `polars_waveform.cx`) does the same in plain Polars.
+
+## Symbolic waveforms
+
+Polars can store Python objects but cannot compute with them. `pw.PandasWaveform` holds such
+values, for example sympy expressions from a symbolic circuit analysis, in the same layout
+(groups, sweep, value) on a pandas Series, which applies Python operators element by element.
+`pw.from_arrays` picks the kind the values need:
+
+```python
+import sympy
+R, C = sympy.symbols("R C", positive=True)
+
+h = pw.from_arrays(freqs, [1 / (1 + 2j * sympy.pi * f * R * C) for f in freqs],
+                   xlabels=["freq"], ylabel="H", xunits=["Hz"])
+h.db20()                                    # still symbolic
+h.map(sympy.simplify)                       # any function, value by value
+h.subs({R: 1e3, C: 1e-9}).bandwidth()       # numbers: measured on numeric()
+```
+
+Measurements and plots run on `numeric()`, the equivalent `Waveform`; it names the free symbols
+while some are left. Needs `pip install "polars-waveform[pandas]"`. Both kinds implement
+`pw.WaveformBase`, the contract for waveform kinds: names, units, `from_arrays` / `to_arrays`,
+arithmetic and the elementwise functions.
+
+## Result sources
+
+`pw.ResultSource` is the shape shared by result objects that hand out waveforms: `leaves`,
+`names`, `v(signal, **params)` and `scan()`. `polars_psf.Result` implements it for simulation
+results; a lab-data handler can implement it too, so analysis code runs on both.
+
+## Development
+
+```sh
+pip install -e ".[test]"
+pytest tests
+ruff check .
+```
+
+## License
+
+MIT.

polars_waveform-0.1.0/README.md

@@ -0,0 +1,164 @@
+# polars-waveform
+
+Waveforms and curve families on [Polars](https://pola.rs), with circuit-style measurements:
+bandwidth, crossings, rise time, phase margin, ... Works on any Polars data: simulation results
+(through [polars-psf](https://github.com/henjo/polars-psf) for Cadence® Spectre® PSF files), lab measurements in Parquet,
+or a DataFrame you built yourself. Pure Python; depends only on `polars`.
+
+polars-waveform is an independent community project, not affiliated with or endorsed by the Polars
+project or by Cadence Design Systems, Inc.
+
+```sh
+pip install polars-waveform          # or: uv add polars-waveform
+```
+
+## Quick start
+
+```python
+import polars as pl
+import polars_waveform as pw
+
+df = pl.DataFrame({"t": [0.0, 1.0, 2.0, 3.0], "v": [0.0, 0.4, 0.9, 1.0]})
+w = pw.Waveform(df, "v")             # the last index column (t) is the sweep
+
+w.ymax(), w.cross(0.5), w.rise_time(), w.value(1.5)
+w.deriv(), w.clip(0.5, 2.5), w * 2 - 1
+```
+
+## Families: one curve per operating point
+
+Index columns besides the sweep are groups. A Waveform then holds a family of curves (devices,
+temperatures, Monte Carlo runs), and every measurement returns a table with one row per curve:
+
+```python
+lf = pl.scan_parquet("lab.parquet")                          # lazy: read on first use
+gain = pw.Waveform(lf.select("dut", "temp", "freq", "gain"), "gain", index=["dut", "temp", "freq"])
+
+gain.bandwidth()                     # dut | temp | bandwidth
+gain.leaf(dut="A1", temp=25.0)       # one curve (a single curve gives plain numbers)
+gain - gain.mean()                   # per-curve results broadcast back over the curves
+```
+
+Those tables are ordinary Polars DataFrames: sort, filter, join with other measurements, and
+`write_csv` / `write_excel`.
+
+Families can also be reshaped, all lazily:
+
+```python
+gain.reduce("min", over="temp")      # worst case over temperature: a family over dut x freq
+gain.ymax(axis="temp")               # the same with an axis argument (axis=-1, the sweep, is per curve)
+gain.reorder(["dut", "freq", "temp"])  # curves over temperature, one per dut and frequency
+for dut, g in gain.along("dut"):     # iterate over one group column
+    print(dut, g.bandwidth())
+gain[-1]                             # last sample of every curve (a number for a single curve)
+gain[10:20]                          # a slice of every curve
+```
+
+## From numpy arrays
+
+`Waveform.from_arrays` takes one array per sweep axis and an n-dimensional `y` (the last axis is
+the sweep, the others become groups), or ragged object arrays; `to_arrays()` converts back:
+
+```python
+w = pw.Waveform.from_arrays([temps, freqs], gain_2d, xlabels=["temp", "freq"], ylabel="gain")
+xs, y = w.to_arrays()
+```
+
+numpy functions keep waveforms as waveforms: `np.abs(w)`, `np.log10(w)`, `array + w`.
+
+## Nested channels
+
+Measurement tables often keep one row per operating point and store each *channel*, a curve
+with its own sweep, in a nested column:
+
+```
+lbw | vdd | idd | ... | pn: {offset: [..], psd: [..]} | spurs: {freq: [..], level: [..]}
+```
+
+`from_nested` turns a channel into a family, one curve per row, without flattening the table.
+Only the group columns and that channel are read:
+
+```python
+pn = pw.from_nested(pl.scan_parquet("pll.parquet"), "pn", x="offset", y="psd",
+                    groups=["lbw", "vdd"], units={"offset": "Hz", "psd": "dBc/Hz"})
+
+pn.value(1e6)                                    # phase noise at 1 MHz offset, per lbw x vdd
+(10 ** (pn / 10)).integ(1e4, 1e7)                # integrated phase noise, per lbw x vdd
+```
+
+Both nested shapes work: a struct of lists (`{x: [..], y: [..]}`) and a list of structs.
+
+## Plotting
+
+```sh
+pip install "polars-waveform[matplotlib]"    # or [altair] for interactive charts
+```
+
+```python
+w.plot()                         # matplotlib: one line per curve, labelled with its group values
+w.semilogx(), w.loglog(), w.stem()
+h.bode()                         # magnitude and phase of a complex response
+w.plot(backend="altair")         # interactive chart (notebooks); pw.set_plot_backend("altair")
+pw.compression_plot(gain_db)     # response, extrapolated line and the compression point
+```
+
+## Measurements
+
+The semantics follow OCEAN, and the OCEAN and pycircuit names are aliases (`pw.dB20`,
+`pw.unityGainFreq`, `pw.riseTime`, `pw.IIP3`, ...):
+
+| | |
+|---|---|
+| values | `value(x)`, `ymax()`, `ymin()`, `xmax()` (x at the largest y), `xmin()`, `average()`/`mean()`, `rms()`, `stddev()` |
+| crossings | `cross(threshold, edge=1, type="either")` (edges from 1, negative from the end), `delay(other, ...)`, `frequency()`, `period()` |
+| transient | `rise_time()`, `fall_time()`, `slew_rate()`, `overshoot()`, `settling_time()` |
+| frequency | `bandwidth(db, "low"/"high"/"band")`, `unity_gain_frequency()`, `phase_margin()`, `gain_margin()` |
+| shape | `deriv()`, `integ(xfrom, xto)`, `iinteg()`, `clip(xfrom, xto)`, `dft()`, `leaf(**groups)` |
+| families | `reduce(how, over)`, `ymax(axis=...)` and friends, `reorder()`, `swapaxes()`, `along()`, `dimension_first()`, `leaf()`, `w[i]`, `w[a:b]` |
+| math | `+ - * /`, `**`, `10 ** w`, `abs()`/`mag()`, `db10()`, `db20()`, `phase()`, `real()`, `imag()`, `conj()`, `log10()`, `exp()`, `sqrt()` |
+| RF | `pw.im2`, `pw.im3`, `pw.iip2`, `pw.iip3`, `pw.compression_point` |
+
+The elementwise functions (`pw.db20`, `pw.phase`, `pw.mag`, ...) also take plain numbers and
+numpy arrays. Complex data is a `Struct{re, im}` column; arithmetic and `db20()`/`phase()` handle it, and
+`pl.col("h").cx.db20()` (registered by `polars_waveform.cx`) does the same in plain Polars.
+
+## Symbolic waveforms
+
+Polars can store Python objects but cannot compute with them. `pw.PandasWaveform` holds such
+values, for example sympy expressions from a symbolic circuit analysis, in the same layout
+(groups, sweep, value) on a pandas Series, which applies Python operators element by element.
+`pw.from_arrays` picks the kind the values need:
+
+```python
+import sympy
+R, C = sympy.symbols("R C", positive=True)
+
+h = pw.from_arrays(freqs, [1 / (1 + 2j * sympy.pi * f * R * C) for f in freqs],
+                   xlabels=["freq"], ylabel="H", xunits=["Hz"])
+h.db20()                                    # still symbolic
+h.map(sympy.simplify)                       # any function, value by value
+h.subs({R: 1e3, C: 1e-9}).bandwidth()       # numbers: measured on numeric()
+```
+
+Measurements and plots run on `numeric()`, the equivalent `Waveform`; it names the free symbols
+while some are left. Needs `pip install "polars-waveform[pandas]"`. Both kinds implement
+`pw.WaveformBase`, the contract for waveform kinds: names, units, `from_arrays` / `to_arrays`,
+arithmetic and the elementwise functions.
+
+## Result sources
+
+`pw.ResultSource` is the shape shared by result objects that hand out waveforms: `leaves`,
+`names`, `v(signal, **params)` and `scan()`. `polars_psf.Result` implements it for simulation
+results; a lab-data handler can implement it too, so analysis code runs on both.
+
+## Development
+
+```sh
+pip install -e ".[test]"
+pytest tests
+ruff check .
+```
+
+## License
+
+MIT.

polars_waveform-0.1.0/polars_waveform/__init__.py

@@ -0,0 +1,49 @@
+"""Waveforms on Polars: curves and curve families with circuit-style measurements.
+
+A :class:`Waveform` is a value column over one or more index columns, backed by a lazy
+``pl.LazyFrame`` and materialized only when a value is needed. The last index column is the
+sweep (time, frequency, offset, ...); any others are groups (corners, Monte Carlo runs, measured
+operating points), so one Waveform can hold a whole family of curves::
+
+    import polars as pl
+    import polars_waveform as pw
+
+    w = pw.Waveform(pl.scan_parquet("lab.parquet"), "gain", index=["dut", "temp", "freq"])
+    w.bandwidth()                  # one row per dut x temp
+    w - w.mean()                   # per-curve results broadcast back over the curves
+    w.leaf(dut="A1", temp=25.0)    # one curve
+
+Measurements follow OCEAN semantics (``xmax`` is the x at the largest y; ``cross`` counts edges
+from 1); the OCEAN and pycircuit spellings (``dB20``, ``unityGainFreq``, ``IIP3``, ...) are aliases.
+Complex data is ``Struct{re, im}``; :mod:`.cx` registers ``pl.col(...).cx`` for it.
+:func:`from_nested` builds families from nested channel columns, :meth:`Waveform.from_arrays`
+from numpy grids, and :class:`ResultSource` is the shape shared by result objects
+(``polars_psf.Result`` implements it). :class:`WaveformBase` is the contract other waveform
+kinds implement; :class:`PandasWaveform` is one for values Polars cannot compute with (sympy
+expressions, ...), and :func:`from_arrays` picks the kind the values need.
+
+Modules: :mod:`.waveform` (the class), :mod:`.functions` (calculator functions), :mod:`.cx`
+(complex helpers), :mod:`.nested`, :mod:`.source`, :mod:`.pandas_waveform`.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from . import cx
+from .base import WaveformBase
+from .functions import *  # noqa: F403
+from .functions import __all__ as _functions
+from .nested import from_nested
+from .pandas_waveform import PandasWaveform, from_arrays
+from .source import ResultSource
+from .waveform import Waveform, either, falling, raising
+
+__all__ = [
+    "PandasWaveform", "ResultSource", "Waveform", "WaveformBase", "cx", "either", "falling", "from_arrays",
+    "from_nested", "raising", *_functions,
+]  # fmt: skip
+
+try:
+    __version__ = _version("polars-waveform")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0+unknown"

polars_waveform-0.1.0/polars_waveform/base.py

@@ -0,0 +1,176 @@
+"""The contract shared by all waveform kinds.
+
+:class:`~polars_waveform.Waveform` stores numeric data in Polars (lazy, families as group
+columns). Other kinds implement the same interface with their own storage, for example a
+symbolic waveform holding sympy expressions in numpy object arrays: Polars can store Python
+objects but has no kernels to compute with them, so such data needs its own container.
+
+A subclass implements storage, construction and elementwise math (the abstract methods), and
+:meth:`WaveformBase.numeric` to turn itself into a numeric :class:`~polars_waveform.Waveform`.
+Measurements it does not implement itself (``bandwidth``, ``cross``, ``rise_time``, ...) are
+inherited from this class and run on ``numeric()``, so they work on any kind once its values are
+numbers.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+__all__ = ["WaveformBase"]
+
+# measurements that need numbers: inherited by other kinds, evaluated on numeric()
+_NUMERIC = (
+    "value", "ymax", "ymin", "xmax", "xmin", "argmax", "argmin", "average", "mean", "rms", "stddev",
+    "cross", "frequency", "period", "rise_time", "fall_time", "slew_rate", "overshoot", "settling_time",
+    "bandwidth", "unity_gain_frequency", "phase_margin", "gain_margin", "integ", "iinteg", "deriv",
+    "clip", "dft", "to_polars", "plot", "semilogx", "semilogy", "loglog", "stem", "bode",
+)  # fmt: skip
+
+
+class WaveformBase(ABC):
+    """A value over one or more index columns: groups (one curve per combination) and a sweep.
+
+    The interface every waveform kind provides: names and units, conversion from and to numpy
+    arrays (:meth:`from_arrays`, :meth:`to_arrays`), arithmetic, the elementwise functions
+    (``db20``, ``phase``, ...), and the measurements, which by default evaluate on
+    :meth:`numeric`.
+    """
+
+    # --- storage and names (abstract) -------------------------------------------------------
+    @classmethod
+    @abstractmethod
+    def from_arrays(cls, x, y, xlabels=None, ylabel=None, xunits=None, yunit=None) -> WaveformBase:
+        """A waveform from numpy arrays: one x array per sweep axis (the last one is the sweep,
+        the others become groups) and ``y`` with shape ``(len(x0), len(x1), ...)``, or ragged
+        object arrays (see :meth:`polars_waveform.Waveform.from_arrays`)."""
+
+    @abstractmethod
+    def to_arrays(self):
+        """``(xs, y)`` as numpy arrays in the layout :meth:`from_arrays` accepts."""
+
+    @abstractmethod
+    def numeric(self):
+        """This waveform as a numeric :class:`~polars_waveform.Waveform`."""
+
+    @property
+    @abstractmethod
+    def index(self) -> list[str]:
+        """Index column names: the groups followed by the sweep."""
+
+    @property
+    def groups(self) -> list[str]:
+        """Index columns other than the sweep (one curve per combination)."""
+        return [c for c in self.index if c != self.xname]
+
+    @property
+    @abstractmethod
+    def xname(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def yname(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def xunit(self): ...
+
+    @property
+    @abstractmethod
+    def yunit(self): ...
+
+    # --- arithmetic (abstract core, shared operators) ------------------------------------------
+    @abstractmethod
+    def _binop(self, other, op: str, *, reverse: bool = False) -> WaveformBase:
+        """``self <op> other`` (``other <op> self`` if ``reverse``) for op in + - * / < > <= >=."""
+
+    def __add__(self, other):
+        return self._binop(other, "+")
+
+    def __radd__(self, other):
+        return self._binop(other, "+", reverse=True)
+
+    def __sub__(self, other):
+        return self._binop(other, "-")
+
+    def __rsub__(self, other):
+        return self._binop(other, "-", reverse=True)
+
+    def __mul__(self, other):
+        return self._binop(other, "*")
+
+    def __rmul__(self, other):
+        return self._binop(other, "*", reverse=True)
+
+    def __truediv__(self, other):
+        return self._binop(other, "/")
+
+    def __rtruediv__(self, other):
+        return self._binop(other, "/", reverse=True)
+
+    def __lt__(self, other):
+        return self._binop(other, "<")
+
+    def __le__(self, other):
+        return self._binop(other, "<=")
+
+    def __gt__(self, other):
+        return self._binop(other, ">")
+
+    def __ge__(self, other):
+        return self._binop(other, ">=")
+
+    # --- elementwise (abstract) ----------------------------------------------------------------
+    @abstractmethod
+    def __neg__(self): ...
+
+    @abstractmethod
+    def __abs__(self): ...
+
+    @abstractmethod
+    def __pow__(self, other): ...
+
+    @abstractmethod
+    def real(self): ...
+
+    @abstractmethod
+    def imag(self): ...
+
+    @abstractmethod
+    def conj(self): ...
+
+    @abstractmethod
+    def phase(self, deg: bool = True): ...
+
+    @abstractmethod
+    def db10(self): ...
+
+    @abstractmethod
+    def db20(self): ...
+
+    def __pos__(self):
+        return self
+
+    def abs(self):
+        """Magnitude (``abs(w)``)."""
+        return abs(self)
+
+    mag = abs
+
+    def conjugate(self):
+        return self.conj()
+
+
+def _numeric_method(name: str):
+    def method(self, *args, **kwargs):
+        num = self.numeric()
+        if type(num) is type(self):  # a numeric kind must implement the measurement itself
+            raise NotImplementedError(f"{type(self).__name__}.{name}()")
+        return getattr(num, name)(*args, **kwargs)
+
+    method.__name__ = name
+    method.__doc__ = f"``{name}`` evaluated on :meth:`numeric` (see ``polars_waveform.Waveform.{name}``)."
+    return method
+
+
+for _name in _NUMERIC:
+    setattr(WaveformBase, _name, _numeric_method(_name))