visualdynamics.gui.author_panel

author_panel

The specification being edited, as tables beside the plot.

What an author states, laid out to be stated: the breakpoints and a level per channel in one grid, every pair's coherence and phase in another with one row that sets them all, and the bands in decibels. The plot beside it draws the autospectra with their bands. One sheet for every door in: a shape set's modal coordinates, a channel table's control channels, a specification opened to edit (Brandon, 2026-09-04: a generic editor, not a modal one).

The two grids are the application's ordinary tables (PLAN.md, "How tables behave"; Brandon, 2026-09-06: every editable table should be the same table): CopyPasteTableView over TableModel columns, so a column header selects the column, a row header the row, Cmd-click adds a cell, and copy, paste, Delete-to-clear, Batch Edit and the fill handle come from the one implementation rather than being written here again. A frequency typed between two others re-sorts the breakpoints rather than refusing them.

Nothing here computes anything. The panel hands back a SpecificationDraft in SI and says when it moved; the window lands every edit on the specification through project.author_specification.

Classes:

Name	Description
Sheet	What the two grids edit: the draft's fields, mutable, in SI.
AuthorPanel	The draft as two grids and the bands; every edit is the object's.

Functions:

Name	Description
sheet_models	(breakpoints, pairs): the sheet's two grids as the ordinary

Classes

Sheet

Sheet(draft: SpecificationDraft, unit_system: UnitSystem)

What the two grids edit: the draft's fields, mutable, in SI.

The models write here cell by cell and the panel reads a draft back whole; the display unit is applied on the way out and undone on the way in, so a cell nobody touched keeps its exact SI value.

Methods:

Name	Description
draft	The sheet as a draft — refused by the draft's own rules for
sort	Breakpoints in frequency order, their levels along — a

Source code in src/visualdynamics/gui/author_panel.py

def __init__(self, draft: SpecificationDraft,
             unit_system: UnitSystem) -> None:
    self.channels: list[str] = list(draft.channels)
    self.dims: list[str] = list(draft.dims)
    self.densities: list[str] = [f'{dim}**2/frequency'
                                 for dim in draft.dims]
    self.frequencies: list[float] = list(draft.frequencies)
    self.levels: list[list[float]] = [list(row) for row in draft.levels]
    self.pairs: dict[tuple[int, int], tuple[float, float] | None] = dict(
        draft.pairs)
    self.pair_keys: list[tuple[int, int]] = draft.pairable()
    self.sources: list[str] = list(draft.sources)
    self.spanning: bool = len(set(draft.sources)) > 1
    self.bands: list[dict] = [dict(entry) for entry in draft.bands]
    self.notes: list[str] = list(draft.notes)
    self.form: str = draft.form
    self.spacing: float | None = draft.spacing
    self.unit_system: UnitSystem = unit_system
    #: set by a frequency edit: the rows have moved and the view
    #: has to be restated rather than repainted
    self.reordered: bool = False

Methods:

draft

draft() -> SpecificationDraft

The sheet as a draft — refused by the draft's own rules for what no specification could hold.

Source code in src/visualdynamics/gui/author_panel.py

def draft(self) -> SpecificationDraft:
    """The sheet as a draft — refused by the draft's own rules for
    what no specification could hold."""
    return SpecificationDraft(
        list(self.channels), list(self.dims), list(self.frequencies),
        [list(row) for row in self.levels], dict(self.pairs),
        self.bands, list(self.notes),
        list(self.sources), self.form, self.spacing)

sort

sort() -> None

Breakpoints in frequency order, their levels along — a frequency typed between two others lands where it belongs (Brandon, 2026-09-06: typed out of order, the sheet stalled).

Source code in src/visualdynamics/gui/author_panel.py

def sort(self) -> None:
    """Breakpoints in frequency order, their levels along — a
    frequency typed between two others lands where it belongs
    (Brandon, 2026-09-06: typed out of order, the sheet stalled)."""
    order = np.argsort(self.frequencies, kind='stable')
    self.frequencies = [self.frequencies[k] for k in order]
    self.levels = [[row[k] for k in order] for row in self.levels]

AuthorPanel

AuthorPanel(parent: QWidget | None = None)

Bases: QWidget

The draft as two grids and the bands; every edit is the object's.

Methods:

Name	Description
show_draft	Lay the draft out, in the display units of each channel's
draft	The draft the sheet holds, in SI. Raises ValueError for

Source code in src/visualdynamics/gui/author_panel.py

def __init__(self, parent: QWidget | None = None) -> None:
    super().__init__(parent)
    self._unit_system = None
    self._sheet: Sheet | None = None
    self._origin_seen: str | None = None
    self._loading = False

    grid = QGridLayout(self)
    grid.setContentsMargins(8, 8, 8, 8)
    grid.setHorizontalSpacing(8)
    grid.setVerticalSpacing(4)
    # a minimum, not a fixed width: the sheet sits in a splitter
    # beside the plot and the user drags it as wide as the grids
    # need (Brandon, 2026-09-06)
    self.setSizePolicy(QSizePolicy.Policy.Preferred,
                       QSizePolicy.Policy.Preferred)
    self.setMinimumWidth(PANEL_WIDTH)

    self.title: QLabel = QLabel('Specification')
    font = self.title.font()
    font.setBold(True)
    self.title.setFont(font)
    # the two forms of one requirement (Brandon, 2026-09-06): the
    # breakpoints it is written from, or the same read onto a
    # controller's frequency lines. Editing is done on the few
    # points; the lines are for the controller's file. Which is
    # showing is the button that is down; the other converts
    head = QHBoxLayout()
    head.addWidget(self.title)
    head.addStretch(1)
    self.form_group: QButtonGroup = QButtonGroup(self)
    self.form_group.setExclusive(True)
    self.breakpoints_button: QPushButton = QPushButton('Breakpoints')
    self.breakpoints_button.setCheckable(True)
    self.breakpoints_button.setToolTip(
        'The few points the requirement is written from — the lines '
        'where its power laws bend')
    self.breakpoints_button.clicked.connect(self._to_breakpoints)
    self.interpolated_button: QPushButton = QPushButton('Interpolated')
    self.interpolated_button.setCheckable(True)
    self.interpolated_button.setToolTip(
        'The same requirement read onto evenly spaced frequency '
        'lines at the spacing beside, as a controller writes its target')
    self.interpolated_button.clicked.connect(self._to_interpolated)
    for button in (self.breakpoints_button, self.interpolated_button):
        self.form_group.addButton(button)
        head.addWidget(button)
    self.spacing_box: DoubleSpinBox = DoubleSpinBox()
    self.spacing_box.setRange(0.0, 100000.0)
    self.spacing_box.setDecimals(4)
    self.spacing_box.setSuffix(' Hz')
    self.spacing_box.setSpecialValueText('spacing?')
    self.spacing_box.setToolTip(
        'The frequency spacing of the interpolated lines — the '
        'specification\'s own, or a time history\'s averaging, '
        'or typed here')
    head.addWidget(self.spacing_box)
    grid.addLayout(head, 0, 0, 1, 4)
    # the bands' two constraints, for every channel of the object:
    # the bands themselves are on the plot, and these say how a
    # drag there moves them
    constraints = QHBoxLayout()
    constraints.addWidget(QLabel('Bands:'))
    self.symmetric_box: QCheckBox = QCheckBox('Symmetric')
    self.symmetric_box.setToolTip(
        'The band above the target is the band below, mirrored; a '
        'drag on one edge moves both')
    self.symmetric_box.toggled.connect(
        lambda on: self._constraint_toggled('symmetric', on))
    self.uniform_box: QCheckBox = QCheckBox('Uniform')
    self.uniform_box.setToolTip(
        'One band over the whole frequency range; a drag anywhere '
        'moves it everywhere')
    self.uniform_box.toggled.connect(
        lambda on: self._constraint_toggled('uniform', on))
    constraints.addWidget(self.symmetric_box)
    constraints.addWidget(self.uniform_box)
    constraints.addStretch(1)
    grid.addLayout(constraints, 1, 0, 1, 4)
    # where the sheet came from, and what a door could not carry
    self.origin: QLabel = QLabel('')
    self.origin.setWordWrap(True)
    self.origin.setEnabled(False)
    grid.addWidget(self.origin, 2, 0, 1, 4)

    # the breakpoints: a row per frequency, a column per channel —
    # the ordinary table, with everything that brings
    self.points: CopyPasteTableView = CopyPasteTableView()
    self.points.setToolTip(
        'The target at each breakpoint, a power law between them — '
        'type a level per channel in the display units shown. Click '
        'a column or row header to select it, Cmd-click to add cells; '
        'copy, paste, Delete to clear, right-click for Batch Edit, '
        'drag the corner handle to fill down')
    self.points.setMinimumHeight(120)
    self.points.edits_applied.connect(self._edits_applied)
    grid.addWidget(self.points, 3, 0, 1, 4)
    buttons = QHBoxLayout()
    self.add_button: QPushButton = QPushButton('Add breakpoint')
    self.add_button.setToolTip('A new breakpoint after the selected one, '
                               'or at the end')
    self.add_button.clicked.connect(self._add_point)
    self.remove_button: QPushButton = QPushButton('Remove breakpoint')
    self.remove_button.setToolTip('Take the selected breakpoints out')
    self.remove_button.clicked.connect(self._remove_point)
    buttons.addWidget(self.add_button)
    buttons.addWidget(self.remove_button)
    buttons.addStretch(1)
    self.scale_box: DoubleSpinBox = DoubleSpinBox()
    self.scale_box.setRange(-60.0, 60.0)
    self.scale_box.setDecimals(2)
    self.scale_box.setSuffix(' dB')
    self.scale_box.setToolTip('Raise or lower the selected levels by '
                              'this much — select a column header for '
                              'a channel, a row header for a breakpoint')
    self.scale_button: QPushButton = QPushButton('Scale selected')
    self.scale_button.clicked.connect(self._scale_selected)
    buttons.addWidget(self.scale_box)
    buttons.addWidget(self.scale_button)
    grid.addLayout(buttons, 4, 0, 1, 4)

    # the pairs: coherence and phase between every two channels,
    # unstated until the author says — independent is a statement
    pairs_label = QLabel('Cross terms')
    pairs_label.setEnabled(False)
    grid.addWidget(pairs_label, 5, 0, 1, 4)
    self.pairs: CopyPasteTableView = CopyPasteTableView()
    self.pairs.setToolTip(
        'The cross term of each pair from its coherence (0 '
        'independent, 1 fully coherent) and phase. A pair left blank '
        'is absent from the specification; Delete clears one')
    self.pairs.setMinimumHeight(110)
    self.pairs.edits_applied.connect(self._edits_applied)
    grid.addWidget(self.pairs, 6, 0, 1, 4)
    all_row = QHBoxLayout()
    all_row.addWidget(QLabel('All pairs:'))
    self.all_coherence: DoubleSpinBox = DoubleSpinBox()
    self.all_coherence.setRange(0.0, 1.0)
    self.all_coherence.setDecimals(3)
    self.all_coherence.setSingleStep(0.1)
    self.all_coherence.setToolTip('Coherence to state for every pair')
    self.all_phase: DoubleSpinBox = DoubleSpinBox()
    self.all_phase.setRange(-180.0, 180.0)
    self.all_phase.setDecimals(1)
    self.all_phase.setSuffix('°')
    self.all_phase.setToolTip('Phase to state for every pair')
    self.all_button: QPushButton = QPushButton('Set')
    self.all_button.setToolTip('State this coherence and phase for '
                               'every pair at once')
    self.all_button.clicked.connect(self._set_all_pairs)
    for widget in (self.all_coherence, self.all_phase, self.all_button):
        all_row.addWidget(widget)
    all_row.addStretch(1)
    grid.addLayout(all_row, 7, 0, 1, 4)

    # the bands are not here: they are dragged on the plot, per
    # section, for every selected channel at once (Brandon,
    # 2026-09-06 — the only place the bands are shown is the plot)
    self.problem: QLabel = QLabel('')
    self.problem.setWordWrap(True)
    grid.addWidget(self.problem, 8, 0, 1, 4)

    # no button: every edit lands on the specification the sheet
    # is open on as it is made (Brandon, 2026-09-06), so switching
    # to another object never leaves an edit behind
    grid.setRowStretch(9, 1)

Methods:

show_draft

show_draft(
    draft: SpecificationDraft,
    unit_system: UnitSystem,
    origin: str = "",
    spacing_hint: float | None = None,
) -> None

Lay the draft out, in the display units of each channel's density. origin says where the sheet came from; spacing_hint the line spacing to offer when the draft remembers none — a time history's averaging, say.

Source code in src/visualdynamics/gui/author_panel.py

def show_draft(self, draft: SpecificationDraft, unit_system: UnitSystem,
               origin: str = '',
               spacing_hint: float | None = None) -> None:
    """Lay the draft out, in the display units of each channel's
    density. `origin` says where the sheet came from;
    `spacing_hint` the line spacing to offer when the draft
    remembers none — a time history's averaging, say."""
    self._unit_system = unit_system
    self._loading = True
    try:
        (self.interpolated_button if draft.form == 'lines'
         else self.breakpoints_button).setChecked(True)
        # the constraints read off the channels: on when every
        # channel of the sheet has them
        self.symmetric_box.setChecked(
            all(entry['symmetric'] for entry in draft.bands))
        self.uniform_box.setChecked(
            all(entry['uniform'] for entry in draft.bands))
        spacing = draft.spacing if draft.spacing is not None else spacing_hint
        self.spacing_box.setValue(spacing if spacing is not None else 0.0)
        said = origin
        if draft.notes:
            said = (said + ' — ' if said else '') + '; '.join(draft.notes)
        self.origin.setText(said)
        self.origin.setVisible(bool(said))
        self._sheet = Sheet(draft, unit_system)
        self._install_models()
    finally:
        self._loading = False
    self._restate()

draft

draft() -> SpecificationDraft

The draft the sheet holds, in SI. Raises ValueError for what no specification could hold.

Source code in src/visualdynamics/gui/author_panel.py

def draft(self) -> SpecificationDraft:
    """The draft the sheet holds, in SI. Raises `ValueError` for
    what no specification could hold."""
    if self._sheet is None:
        raise ValueError('no sheet is open')
    return self._sheet.draft()

Functions:

sheet_models

sheet_models(
    sheet: Sheet, parent: Any = None
) -> tuple[TableModel, TableModel]

(breakpoints, pairs): the sheet's two grids as the ordinary table models — the conventions test holds them to the contract. The cells journal through the verb the window calls on every edit, so each column is declared journalled elsewhere.

Source code in src/visualdynamics/gui/author_panel.py

def sheet_models(sheet: Sheet, parent: Any = None
                 ) -> tuple[TableModel, TableModel]:
    """(breakpoints, pairs): the sheet's two grids as the ordinary
    table models — the conventions test holds them to the contract.
    The cells journal through the verb the window calls on every edit,
    so each column is declared journalled elsewhere."""
    unit_system = sheet.unit_system
    points = [Column('Hz', lambda s, r: s.frequencies[r], set=_set_frequency,
                     format=lambda v: f'{v:g}', journal=_elsewhere)]
    for k, (name, density) in enumerate(zip(sheet.channels, sheet.densities)):
        title = ((f'{sheet.sources[k]}\n' if sheet.spanning else '')
                 + f'{name}\n{unit_system.label_text(density)}')
        points.append(Column(title, _level_getter(k), set=_level_setter(k),
                             format=lambda v: f'{v:.6g}', journal=_elsewhere))
    pairs = [Column('Pair', _pair_label),
             Column('Coherence', _pair_getter(0), set=_pair_setter(0),
                    format=_number_text, journal=_elsewhere),
             Column('Phase °', _pair_getter(1), set=_pair_setter(1),
                    format=_number_text, journal=_elsewhere)]
    return (TableModel(sheet, points, lambda s: len(s.frequencies), parent),
            TableModel(sheet, pairs, lambda s: len(s.pair_keys), parent))