visualdynamics 0.1.0a74__tar.gz → 0.1.0a76__tar.gz

{visualdynamics-0.1.0a74/src/visualdynamics.egg-info → visualdynamics-0.1.0a76}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visualdynamics
-Version: 0.1.0a74
+Version: 0.1.0a76
 Summary: Structural Dynamics Visualization: a units-aware structural dynamics analysis toolset
 Author-email: Brandon Zwink <bzwink@gmail.com>
 License-Expression: MIT
@@ -16,6 +16,7 @@ Classifier: Topic :: Scientific/Engineering :: Visualization
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
 Classifier: Environment :: X11 Applications :: Qt
 Requires-Python: >=3.12
@@ -29,7 +30,7 @@ Requires-Dist: h5py
 Requires-Dist: netCDF4
 Requires-Dist: pint
 Requires-Dist: pyvista
-Requires-Dist: pyvistaqt
+Requires-Dist: pyvistaqt>=0.13
 Requires-Dist: vtk
 Requires-Dist: PySide6
 Requires-Dist: shiboken6

{visualdynamics-0.1.0a74 → visualdynamics-0.1.0a76}/pyproject.toml

@@ -33,6 +33,7 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Operating System :: OS Independent",
     "Environment :: X11 Applications :: Qt",
 ]
@@ -70,7 +71,13 @@ dependencies = [
     "netCDF4",
     "pint",
     "pyvista",
-    "pyvistaqt",
+    # 0.13 made the 3-D view a QOpenGLWidget that Qt composes with the
+    # rest of the window, and the window is built for that: Qt Quick
+    # draws with OpenGL and every context has the views' format from
+    # the start (gui.opengl.one_graphics_system). A Mac still on 0.11.4
+    # crashed generating a report under that setup (2026-10-27); the
+    # floor has pip upgrade such an environment rather than leave it.
+    "pyvistaqt>=0.13",
     # BSD-3-Clause. pyvista brings it, but this package imports
     # `vtkmodules` directly — the stage's marks, the drag picking, the
     # scene's axes — and what is imported is declared here rather than
@@ -189,10 +196,14 @@ line-length = 100
 # — forty-six seconds, which was most of the suite's wall clock and none
 # of it about the package. The rules that *are* about the package are
 # stated on a three-quad strip in test_fem.py instead. Run the demo's own
-# suite with `pytest -m slow` (CI does, in a step of its own).
+# suite with `pytest -m slow` (CI does, in a job of its own).
+# `guide` marks the slow tests that are minutes of meshing each, the
+# guide's tetrahedra table: CI runs them on main and weekly, not on a
+# pull request (2026-10-28), and `-m slow` here still runs them.
 addopts = '-n auto -m "not slow"'
 markers = [
     "slow: the demonstration model, built for the website and the docs — run on demand rather than on every edit",
+    "guide: the guide's mesh table, minutes of meshing a shape — checked on main and weekly, not on every pull request",
 ]
 filterwarnings = [
     # netCDF4's published wheel is built against an older numpy C API; the

{visualdynamics-0.1.0a74 → visualdynamics-0.1.0a76}/src/visualdynamics/__init__.py

@@ -97,7 +97,7 @@ from .units import (
 #: alpha, said in the version itself so the dialog, the About text, the
 #: installers and latest.json all say the same thing, and the first
 #: non-alpha release is offered as an upgrade (Brandon, 2026-09-11)
-__version__ = '0.1.0a74'
+__version__ = '0.1.0a76'
 
 
 def launch_gui(*paths: str, in_process: bool | None = None) -> Any:

{visualdynamics-0.1.0a74 → visualdynamics-0.1.0a76}/src/visualdynamics/compatibility.py

@@ -22,8 +22,8 @@ A data object whose DOFs are all modal coordinates (`M1` ... `Mn`, see
 the one it was transformed or computed through, and fits wherever there
 is a set with at least as many modes as it names: a set in its object
 group when it is in one, any set in the project otherwise. A time
-history can hold both kinds of record, forces with the modal responses
-computed from them appended: its physical records answer to the
+history can hold both kinds of record, forces merged with the modal
+responses computed from them: its physical records answer to the
 geometry and its modal records to the shape sets, each by its own rule.
 
 Not checked here:

{visualdynamics-0.1.0a74 → visualdynamics-0.1.0a76}/src/visualdynamics/core/author.py

@@ -1907,11 +1907,19 @@ def read_at_lines(old_f: np.ndarray, values: np.ndarray,
     """A specification record read at new lines.
 
     At its own lines the record keeps its own values. Between them it
-    is interpolated the way a specification is read, the magnitude
-    log-log and the phase linearly, so a line the sheet added does not
-    change what a channel the sheet does not hold means. Outside its
-    range it takes its end values.
+    is interpolated the way a specification is read, so a line the
+    sheet added does not change what a channel the sheet does not hold
+    means: a cross term by `compliance.cross_term_at` (the magnitude
+    log-log between points above zero, straight through a zero, the
+    phase linearly), a real record by its magnitude log-log over the
+    points above zero. Outside its range it takes its end values.
     """
+    # A cross term was read here by its own rule, bridging a zero at a
+    # breakpoint as a gap, and the drive prediction read the sheet's
+    # rule while the matrix comparison read the specification's: the
+    # same cross term gave two coherences (2026-10-28). One reader now.
+    from .compliance import cross_term_at
+
     values = np.asarray(values)
     exact = np.isin(lines, old_f)
     if exact.all():
@@ -1923,16 +1931,19 @@ def read_at_lines(old_f: np.ndarray, values: np.ndarray,
     out = np.full(len(lines), np.nan, dtype=values.dtype)
     out[exact] = values[np.searchsorted(old_f, lines[exact])]
     new = ~exact
+    if np.iscomplexobj(values):
+        written = np.isfinite(values)
+        read = cross_term_at(old_f[written], values[written], lines[new])
+        # the end values outside the range, as the real branch holds them
+        below, above = lines[new] < old_f[0], lines[new] > old_f[-1]
+        read[below], read[above] = values[0], values[-1]
+        out[new] = read
+        return out
     if positive.sum() >= 2:
         size = np.exp(np.interp(log_new[new], log_old[positive],
                                 np.log(magnitude[positive])))
     else:
         size = np.interp(lines[new], old_f, np.nan_to_num(magnitude))
-    if np.iscomplexobj(values):
-        phase = np.interp(lines[new], old_f,
-                          np.unwrap(np.angle(values)))
-        out[new] = size * np.exp(1j * phase)
-    else:
-        out[new] = size * np.sign(np.interp(lines[new], old_f,
-                                            np.nan_to_num(values)))
+    out[new] = size * np.sign(np.interp(lines[new], old_f,
+                                        np.nan_to_num(values)))
     return out

{visualdynamics-0.1.0a74 → visualdynamics-0.1.0a76}/src/visualdynamics/core/channel_table.py

@@ -484,7 +484,13 @@ class ChannelTable:
 
         A unit that is not of the channel's declared type is refused;
         change the type first. Changing the type clears a unit of another
-        kind.
+        kind. A model in the sensor catalog (`core.sensor_catalog`) fills
+        a blank Make with its maker; a make already written is kept. A
+        triaxial accelerometer's model or serial number is written once:
+        the other acceleration rows at its node, its other legs, get its
+        Make, Model and Serial Number where theirs are blank (and their
+        model is blank or the same). A row of another type at that node,
+        a force gauge, is never filled.
 
         Parameters
         ----------
@@ -537,6 +543,43 @@ class ChannelTable:
                 from ..units import dimension_of
                 if dimension_of(unit) != coerced:
                     self.frame.loc[row, 'unit'] = ''
+        if name == 'model' and coerced:
+            # picking a model names its maker too (Brandon, 2026-10-26)
+            from .sensor_catalog import lookup
+
+            entry = lookup(str(coerced))
+            if entry is not None and not str(self.frame.loc[row, 'make']).strip():
+                self.frame.loc[row, 'make'] = entry.make
+        if name in ('model', 'serial_number') and coerced:
+            self._fill_triax(row)
+
+    def _fill_triax(self, row: int) -> None:
+        """Copy a triax row's Make, Model and Serial Number into the blank
+        cells of its other legs: the other acceleration rows at its node
+        whose model is blank or the same. Only a model the catalog knows
+        is a triax is spread, and only into acceleration rows."""
+        # Brandon, 2026-10-27: a triax's identity typed three times was
+        # one too many; legs wired one or two at a time are why the cells
+        # are filled rather than merged, and a force gauge at the node is
+        # why the type has to match.
+        from .sensor_catalog import lookup
+
+        frame = self.frame
+        entry = lookup(str(frame.loc[row, 'model']))
+        node = str(frame.loc[row, 'node']).strip()
+        if (entry is None or entry.kind != 'triax' or not node
+                or str(frame.loc[row, 'channel_type']) != 'acceleration'):
+            return
+        for other in range(self.num_channels):
+            if (other == row or str(frame.loc[other, 'node']).strip() != node
+                    or str(frame.loc[other, 'channel_type']) != 'acceleration'):
+                continue
+            model = str(frame.loc[other, 'model']).strip()
+            if model and lookup(model) is not entry:
+                continue
+            for column in ('make', 'model', 'serial_number'):
+                if not str(frame.loc[other, column]).strip():
+                    frame.loc[other, column] = frame.loc[row, column]
 
     def _agrees_with_type(self, row: int, unit: str) -> None:
         """A declared type and a unit have to describe one channel."""

{visualdynamics-0.1.0a74 → visualdynamics-0.1.0a76}/src/visualdynamics/core/classical_pulse.py

@@ -906,28 +906,14 @@ def check_pulse(history: TimeHistory, pulse: ClassicalPulse,
 def pulse_channel(history: TimeHistory,
                   channel: int | str | None = None) -> int:
     """The row of `history` a pulse is read from: `channel` by index or
-    DOF, or the first acceleration channel; refused when it is not an
-    acceleration, since a pulse's velocity change is the area under an
-    acceleration and nothing else."""
-    rows = range(history.num_records)
-    if channel is None:
-        row = next((i for i in rows
-                    if history.known_dim(i) == 'acceleration'), None)
-        if row is None:
-            raise ValueError('a pulse is read from an acceleration, and '
-                             'this record holds none')
-        return row
-    if isinstance(channel, str):
-        dofs = [str(dof) for dof in history.response_dof]
-        if channel not in dofs:
-            raise ValueError(f'the record has no channel {channel}')
-        row = dofs.index(channel)
-    else:
-        row = int(channel)
-        if not 0 <= row < history.num_records:
-            raise ValueError(f'the record has {history.num_records} '
-                             f'channels; there is no channel {row}')
-    if history.known_dim(row) != 'acceleration':
-        raise ValueError(f'{history.response_dof[row]} is not an '
-                         'acceleration, and a pulse is read from one')
-    return row
+    DOF, or the first acceleration channel whose unit is declared
+    (`core.shaker.acceleration_channel`, the one rule for the stroke
+    and the replication fit too); refused otherwise, since a pulse's
+    velocity change is the area under an acceleration in a known scale
+    and nothing else."""
+    # It read a channel by `known_dim` (2026-10-28), so a record whose
+    # unit was only hinted was judged raw against an SI nominal: a 50 g
+    # half-sine stored in g passed as 5.1 g with every point inside.
+    from .shaker import acceleration_channel
+
+    return acceleration_channel(history, channel)

{visualdynamics-0.1.0a74 → visualdynamics-0.1.0a76}/src/visualdynamics/core/compliance.py

@@ -88,6 +88,116 @@ def log_interpolate(frequencies: ArrayLike, spec_frequencies: ArrayLike,
     return out
 
 
+def cross_term_at(frequencies: ArrayLike, values: ArrayLike,
+                  lines: ArrayLike) -> np.ndarray:
+    """A cross term written at breakpoints, read at `lines` the way a
+    specification is drawn: the magnitude log-log between two points
+    that are both above zero and straight between two that are not (a
+    coherence of zero, two channels stated to be independent, is a
+    value and not a gap), the phase linearly. Not a number outside the
+    points, and at lines at or below zero hertz.
+
+    Parameters
+    ----------
+    frequencies : array_like
+        The breakpoints' frequencies, in Hz, in any order.
+    values : array_like
+        The complex cross term at each breakpoint.
+    lines : array_like
+        Where to read it.
+
+    Returns
+    -------
+    numpy.ndarray
+        Complex, one value per line.
+    """
+    # Two readers of this existed, one in the matrix comparison and one
+    # in the drive prediction through the authoring sheet, and they
+    # disagreed on a zero at a breakpoint: the sheet's bridged it as a
+    # gap, so one specification read 0.81 coherence in the prediction
+    # and 0.32 in the comparison at the same line (2026-10-28). This is
+    # the one reader, and the zero is a statement.
+    frequencies = np.asarray(frequencies, dtype=float)
+    values = np.asarray(values)
+    lines = np.asarray(lines, dtype=float)
+    usable = np.isfinite(frequencies) & (frequencies > 0.0)
+    order = np.argsort(frequencies[usable])
+    f = frequencies[usable][order]
+    v = values[usable][order].astype(complex)
+    out = np.full(lines.shape, np.nan, dtype=complex)
+    if f.size < 2:
+        return out
+    inside = (lines >= f[0]) & (lines <= f[-1])
+    at = lines[inside]
+    k = np.clip(np.searchsorted(f, at, side='right') - 1, 0, f.size - 2)
+    m1, m2 = np.abs(v[k]), np.abs(v[k + 1])
+    part = (at - f[k]) / (f[k + 1] - f[k])
+    with np.errstate(divide='ignore', invalid='ignore'):
+        logs = np.exp(np.log(m1) + (np.log(m2) - np.log(m1))
+                      * np.log(at / f[k]) / np.log(f[k + 1] / f[k]))
+    magnitude = np.where((m1 > 0.0) & (m2 > 0.0), logs,
+                         m1 + (m2 - m1) * part)
+    phase = np.interp(at, f, np.unwrap(np.angle(v)))
+    out[inside] = magnitude * np.exp(1j * phase)
+    return out
+
+
+def record_at(data: Any, record: int, lines: ArrayLike) -> np.ndarray:
+    """One record of a specification read at `lines`, the way it is
+    drawn, and not a number where it is not written.
+
+    An autospectrum is written where it is above zero, and between
+    breakpoints ('log_log') is read log-log with its gaps
+    (`log_interpolate`). A cross term is written wherever it is a
+    number, zero included, and is read between breakpoints by
+    `cross_term_at`; whether its coherence is defined is for its two
+    autospectra to say. On lines or bands ('bin') a record takes the
+    value of the bin the line falls in. The matrix comparison and the
+    drive prediction both read a specification here.
+
+    Parameters
+    ----------
+    data : Psd or Specification
+        The specification.
+    record : int
+        Which record.
+    lines : array_like
+        Where to read it, in Hz.
+
+    Returns
+    -------
+    numpy.ndarray
+        Real for an autospectrum, complex for a cross term.
+    """
+    from .data import autospectrum
+
+    lines = np.asarray(lines, dtype=float)
+    frequencies = np.asarray(data.abscissa, dtype=float)
+    values = np.asarray(data.ordinate)[record]
+    auto = autospectrum(data, record)
+    written = np.isfinite(frequencies) & (
+        data.written(record) if auto else np.isfinite(values))
+    if getattr(data, 'interpolation', 'bin') == 'log_log':
+        if auto:
+            return log_interpolate(lines, frequencies, np.real(values))
+        return cross_term_at(frequencies[written], values[written], lines)
+    left, right = data.bin_bounds()
+    order = np.argsort(left)
+    left, right = left[order], right[order]
+    out = np.full(lines.shape, np.nan, dtype=float if auto else complex)
+    if not left.size:
+        return out
+    # the last bin starting at or below each line, if that bin reaches it
+    k = np.searchsorted(left, lines, side='right') - 1
+    found = k >= 0
+    k = np.maximum(k, 0)
+    found &= (lines >= left[k]) & (lines < right[k])
+    source = order[k]
+    found &= written[source]
+    out[found] = (np.real(values) if auto else values)[source[found]]
+    return out
+
+
 def log_log_areas(frequencies: ArrayLike, values: ArrayLike,
                   lows: ArrayLike, highs: ArrayLike) -> np.ndarray:
     """The exact area under the log-log curve through these points, over
@@ -423,6 +533,24 @@ def cells(specification: Specification, measured: DataArray,
     return out
 
 
+def cell_lines(cell: dict[str, Any], left: np.ndarray,
+               right: np.ndarray) -> slice | None:
+    """The measured lines one cell of `cells` reaches, as a slice of
+    the bins whose edges are `left` and `right` (sorted), or None when
+    it reaches none.
+
+    Found by where the cell's ends fall among the bins: a bin that ends
+    where the cell begins shares an edge and no width, and is not in
+    it. `judge` marks the lines of an out cell by this, and a reading
+    that spreads a cell's result over its lines uses the same rule.
+    """
+    first = int(np.searchsorted(right, cell['low'] * (1.0 + 1e-12),
+                                side='right'))
+    last = int(np.searchsorted(left, cell['high'] * (1.0 - 1e-12),
+                               side='left'))
+    return slice(first, last) if last > first else None
+
+
 def judge(specification: Specification, measured: DataArray,
           spec_record: int = 0, measured_record: int = 0,
           limit: str | None = 'abort_upper', over: bool = True,
@@ -494,16 +622,11 @@ def judge(specification: Specification, measured: DataArray,
     lines = np.zeros(left.shape, dtype=bool)
     level = np.full(left.shape, np.nan)
     start, stop = left.copy(), right.copy()
-    # the lines each out cell reaches, found by where the cell's ends
-    # fall among the sorted bins: a bin that ends where the cell
-    # begins shares an edge and no width, and is not in it
     for k in np.flatnonzero(out):
         cell = found[k]
-        first = int(np.searchsorted(right, cell['low'] * (1.0 + 1e-12), side='right'))
-        last = int(np.searchsorted(left, cell['high'] * (1.0 - 1e-12), side='left'))
-        if last <= first:
+        inside = cell_lines(cell, left, right)
+        if inside is None:
             continue
-        inside = slice(first, last)
         lines[inside] = True
         level[inside] = asked[k] / cell['width']
         start[inside] = np.maximum(left[inside], cell['low'])
@@ -816,6 +939,7 @@ def detect_scale_db(specification: Specification, measured: DataArray,
     # the same bands. `significant_band` is there because a waveform's
     # spectrum ending at 2 kHz left half a transient's bands 40 dB apart,
     # saying nothing about level.
+    from .data import autospectrum
     from .octave import PER_OCTAVE
 
     if comparable(specification, measured) is not None:
@@ -833,6 +957,10 @@ def detect_scale_db(specification: Specification, measured: DataArray,
         if wanted is not None and label not in wanted and str(
                 specification.response_dof[spec_index]) not in wanted:
             continue
+        # a cross term has no level to read a scale from: its real part
+        # moves with its phase
+        if not autospectrum(specification, spec_index):
+            continue
         # a pair the comparison refuses has no level to read a scale from
         if units_check(specification.ordinate_dim[spec_index],
                        measured.ordinate_dim[measured_index])[0] is not None:
@@ -973,6 +1101,16 @@ def exceedances(specification: Specification, measured: DataArray,
     return marks[0], marks[1]
 
 
+#: why `compare` does not read a cross term. A cross spectrum is complex,
+#: and its real part is not the power of either channel: read as a
+#: level, a cross term held at its specified magnitude but 60 degrees
+#: off its phase came out 3 dB low, and one 120 degrees off had no
+#: level at all. Its coherence and phase are what is judged
+#: (`core.matrix_comparison`).
+CROSS_TERM_REFUSAL = ('a cross term is judged by its coherence and phase '
+                      '(the matrix comparison), not by its level')
+
+
 def compare(specification: Specification, measured: DataArray,
             spec_record: int = 0,
             measured_record: int = 0,
@@ -992,17 +1130,20 @@ def compare(specification: Specification, measured: DataArray,
     fraction of its bin that was judged, so a band at the top of the
     range counts the same as one at the bottom.
 
-    A pair of objects that cannot be compared (`comparable`), or a pair
+    A pair of objects that cannot be compared (`comparable`), a pair
     of records of different quantities or with only one side's units
-    declared (`units_check`), returns {'lines': 0, 'refused': reason},
-    and one with nothing to compare returns {'lines': 0}. With neither
-    side's units declared the pair is compared and the result carries
-    'note' (`RAW_NOTE`).
+    declared (`units_check`), or a specification record that is a cross
+    term (`CROSS_TERM_REFUSAL`), returns {'lines': 0, 'refused':
+    reason}, and one with nothing to compare returns {'lines': 0}. With
+    neither side's units declared the pair is compared and the result
+    carries 'note' (`RAW_NOTE`).
 
     Every number is of the scaled measurement: `scale_db` is resolved
     through `comparison_scale_db` unless given, and is returned so a
     table can say what was compared.
     """
+    from .data import autospectrum
+
     if scale_db is None:
         scale_db = comparison_scale_db(specification, measured)
     # the level, cell by cell: both integrated over the very same
@@ -1013,6 +1154,8 @@ def compare(specification: Specification, measured: DataArray,
     refused = comparable(specification, measured)
     if refused is not None:
         return {'lines': 0, 'refused': refused}
+    if not autospectrum(specification, spec_record):
+        return {'lines': 0, 'refused': CROSS_TERM_REFUSAL}
     refused, note = units_check(specification.ordinate_dim[spec_record],
                                 measured.ordinate_dim[measured_record],
                                 wanted_name='the specification')
@@ -1284,10 +1427,11 @@ def compare_all(specification: Specification, measured: DataArray,
     result from `compare`.
 
     A specification bounds the control channels, and a measurement
-    usually holds those and many more. Channels are paired by DOF, the
-    response and the reference where there is one (`matched_records`),
-    so a cross spectrum is compared with the specification's cross term
-    if it has one and is left out if it does not.
+    usually holds those and many more. Channels are paired by DOF and
+    quantity (`matched_records`). Only the specification's autospectra
+    are compared here: a cross term is not a level, and its coherence
+    and phase are judged by `core.matrix_comparison.compare_matrix`,
+    which compares the autospectra through this same function.
 
     Rows are in the specification's order, the order a control room
     reads its channels in. The scale is resolved once for the whole set,
@@ -1301,24 +1445,46 @@ def compare_all(specification: Specification, measured: DataArray,
     'scale_db', but `channel_errors` and the charts built from it do
     not. Pass `scale_db=0` to compare as measured.
     """
-    # the warning is there because a whole campaign was once scored on
-    # shifted numbers without a word (2026-09-26)
-    if scale_db is None:
-        scale_db = comparison_scale_db(specification, measured,
-                                       spec_records, measured_records)
-        if scale_db and getattr(measured, 'scale_db', None) is None:
-            import warnings
-
-            warnings.warn(
-                f'the measurement was scaled by {scale_db:+g} dB, detected '
-                f'from the data as a run at {-scale_db:+g} dB; pass '
-                'scale_db=0 to compare it as measured, or set '
-                'measured.scale_db to the level it was run at',
-                ScaleWarning, stacklevel=2)
+    from .data import autospectrum
+
+    scale_db = resolved_scale_db(specification, measured, spec_records,
+                                 measured_records, scale_db, stacklevel=3)
+    # cross terms out since 2026-10-24: `compare` read one by its real
+    # part, which moves with its phase
     return [(label, compare(specification, measured, spec_index,
                             measured_index, scale_db=scale_db))
             for label, spec_index, measured_index in matched_records(
-                specification, measured, spec_records, measured_records)]
+                specification, measured, spec_records, measured_records)
+            if autospectrum(specification, spec_index)]
+
+
+def resolved_scale_db(specification: Specification, measured: DataArray,
+                      spec_records: Sequence[int] | None = None,
+                      measured_records: Sequence[int] | None = None,
+                      scale_db: float | None = None,
+                      stacklevel: int = 2) -> float:
+    """The one scale a whole set of comparisons is made at: `scale_db`
+    when given, else `comparison_scale_db`'s, with a `ScaleWarning`
+    when that scale was detected from the data rather than set on the
+    measurement. `compare_all` and the matrix comparison resolve their
+    scale here, so both warn alike. `stacklevel` points the warning at
+    the caller's caller."""
+    # the warning is there because a whole campaign was once scored on
+    # shifted numbers without a word (2026-09-26)
+    if scale_db is not None:
+        return scale_db
+    scale_db = comparison_scale_db(specification, measured,
+                                   spec_records, measured_records)
+    if scale_db and getattr(measured, 'scale_db', None) is None:
+        import warnings
+
+        warnings.warn(
+            f'the measurement was scaled by {scale_db:+g} dB, detected '
+            f'from the data as a run at {-scale_db:+g} dB; pass '
+            'scale_db=0 to compare it as measured, or set '
+            'measured.scale_db to the level it was run at',
+            ScaleWarning, stacklevel=stacklevel)
+    return scale_db
 
 
 #: The RMS dB deviation an SRS comparison is shaded past, either side.